Awesome-omni-skill investigation-codex-vscode-extension

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.

install

source · Clone the upstream repo

git clone https://github.com/diegosouzapw/awesome-omni-skill

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/diegosouzapw/awesome-omni-skill "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/tools/investigation-codex-vscode-extension" ~/.claude/skills/diegosouzapw-awesome-omni-skill-investigation-codex-vscode-extension && rm -rf "$T"

manifest: skills/tools/investigation-codex-vscode-extension/SKILL.md

source content

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)

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.

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

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
```
  .
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).
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
```
  ).
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.
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.