investigation-codex-vscode-extension

name	investigation-codex-vscode-extension
description	This skill should be used when investigating why the Codex VS Code extension fails to spawn or connect to a local Codex agent, especially after updates or CLI changes.

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.