Investigation: Codex VS Code Extension

[Created by Codex: 019be564-39d9-7b12-a4cf-fb7a7f1af223 2026-01-22]

Purpose

Provide a fast, repeatable workflow to diagnose why the Codex VS Code extension cannot spawn or connect to the local codex app-server.

When to Use

Use when a user reports that Codex in VS Code will not start, errors on spawn, or fails after an extension or CLI update.

Warning Flags (Check First)

• Non-default CLI override is set: If "chatgpt.cliExecutable" is configured, the extension will run that binary instead of the bundled 45MB codex.
• Assume “custom build” risk: An override often points at a locally built or modified Codex repo; the user must know exactly what it is and why it differs.
• Always surface it explicitly: State the resolved codex path and codex --version in the RCA, and ask the user to confirm the repo/build they intended to run.

Incident Example (2026-01-22)

• Symptom: “Cannot spawn a Codex agent in VS Code” after updating the extension to openai.chatgpt 0.4.62.
• Root cause: The extension started codex app-server --analytics-default-enabled, but the user had "chatgpt.cliExecutable" pinned to a codex-cli 0.77.0 binary that did not recognize that flag, so the process exited with code 2.
• Evidence: ~/Library/Application Support/Code/logs/.../window*/exthost/openai.chatgpt/Codex.log contained error: unexpected argument '--analytics-default-enabled' found.
• Fix: Remove or update "chatgpt.cliExecutable" to a compatible codex binary (or let the extension use its bundled one), then reload VS Code.

Workflow (Non-Invasive)

1. Identify the actual codex binary VS Code is running (this is frequently the root cause):

- Check for "chatgpt.cliExecutable" in: - ~/Library/Application Support/Code/User/settings.json - <repo>/.vscode/settings.json - If set, treat it as a high-priority hypothesis: VS Code is running a non-default codex (often a custom build). - If set, tell the user the resolved path and ask them to confirm which repo/build that binary came from.

1. Identify extension version and entrypoint:

- ls ~/.vscode/extensions | rg -i 'openai.chatgpt' - cat ~/.vscode/extensions/<ext>/package.json (read main) - rg -n -- 'spawn|CLI_EXECUTABLE|codex|app-server' ~/.vscode/extensions/<ext>/out/extension.js

1. Determine which codex binary the extension uses:

- If "chatgpt.cliExecutable" is set, it wins. - Otherwise, the fallback is typically: ~/.vscode/extensions/<ext>/bin/<platform>/codex.

1. Pull extension logs (most authoritative):

- ~/Library/Application Support/Code/logs/<latest>/window*/exthost/openai.chatgpt/Codex.log - .../exthost/exthost.log for activation and stack traces. - Prioritize explicit CLI errors (unknown flags, ENOENT, EACCES, exit code).

1. Correlate failure with CLI arguments:

- Compare args in extension.js with codex app-server --help for the selected binary. - If flags mismatch, conclude the extension is running an older CLI (often via chatgpt.cliExecutable).

1. Run sanity checks:

- Compare codex --version for (a) terminal PATH (b) configured chatgpt.cliExecutable target (c) extension-bundled binary. - Verify executable permissions or quarantine status on macOS when EACCES appears.

1. Draft RCA and minimal fix:

- Cite the exact log line and file path. - Provide the smallest fix: remove/update chatgpt.cliExecutable, point to newer binary, reload window.

Common Root Causes

• chatgpt.cliExecutable pinned to an older CLI missing new flags.
• Extension update changed CLI arguments but local binary stayed old.
• Missing or non-executable bundled binary after update.
• macOS quarantine or code signing issues (EACCES).

Output Expectations

• Provide a short RCA (1–3 bullets) and minimal fix steps.
• Avoid invasive code changes unless explicitly requested.