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.
2. •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
3. •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.
4. •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).
5. •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).
6. •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.
7. •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.