Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
168 lines (114 loc) · 3.75 KB

TROUBLESHOOTING.md

File metadata and controls

168 lines (114 loc) · 3.75 KB

Troubleshooting

Start with the MCP resources codex://status and codex://doctor. They do not invoke a model and are safe to read during installation or debugging.

Codex Binary Is Not Found

Run:

npm run build
claude --plugin-dir .

Then ask Claude to read codex://status.

The resolver prefers:

  1. Per-call codex_bin.
  2. CODEX_SUBAGENTS_CODEX_BIN.
  3. /Applications/Codex.app/Contents/Resources/codex.
  4. CODEX_BIN.
  5. codex on PATH.

If needed, set:

export CODEX_SUBAGENTS_CODEX_BIN=/absolute/path/to/codex

Claude Does Not Pick The Plugin

Check that Claude was started with the plugin directory:

claude --plugin-dir .

For installed-plugin development, run:

npm run install:local
npm run dev:watch

Then ask Claude to use Codex naturally, for example:

Ask Codex to review this repository read-only.

The plugin includes a skill and front-door tools so Claude should not need to know the low-level tool names.

A Long Run Times Out

Prefer the native background/follow-up flow for long work:

  • codex_task with background: true
  • codex_followup with mode: "wait"
  • codex_followup with mode: "steer"

Persistent sessions are the better choice when the work must survive an MCP restart. Async one-shot jobs are process-local and do not survive restarts.

Session Recovery Fails

Use codex_followup with mode: "wait" first. If the server restarted, start a new codex_task unless you are deliberately using hidden debug session tools.

Check:

  • whether the session has a codexThreadId
  • whether it used protocol: "app-server"
  • whether supports.threadResume is true
  • whether thread/read is unavailable but recovery still succeeded

If app-server is unavailable, the plugin falls back to exec sessions unless CODEX_SUBAGENTS_DISABLE_EXEC_FALLBACK=1 is set.

Tool Results Are Too Large

The plugin compacts large responses before returning them to Claude. If mcpResponse.compacted is true, inspect the returned summary first. Full retained stdout/stderr/final-message artifacts are written under the artifact directory when output artifacts are enabled.

Useful settings:

export CODEX_SUBAGENTS_OUTPUT_ARTIFACTS=1
export CODEX_SUBAGENTS_ARTIFACT_DIR=/tmp/codex-subagents-artifacts

Debug Logs

Verbose JSONL logging is on by default and goes to stderr. To also write a file:

export CODEX_SUBAGENTS_LOG_FILE=/tmp/codex-subagents.log
export CODEX_SUBAGENTS_LOG_LEVEL=debug

The default debug profile intentionally logs raw MCP traffic. Treat logs as sensitive project data.

For quieter local usage:

export CODEX_SUBAGENTS_LOG_PROFILE=production

To disable logging:

export CODEX_SUBAGENTS_LOG_LEVEL=silent

Export A Debug Bundle

Set CODEX_SUBAGENTS_ENABLE_DEBUG_TOOLS=1 and ask Claude to call codex_export_debug_bundle, or run:

npm run diagnostics

Bundles include status, selected session/job state, recent failures, queue/session limits, logging/artifact settings, lifecycle stats, and a bounded log tail when a log file is configured.

Real Claude/Codex Validation

Use fake-Codex Claude tests first:

npm run test:claude-autodiscovery
npm run test:claude-orchestration
npm run test:claude-session-steering

Then use real Codex tests only when needed:

npm run test:real-app-server-steering
npm run test:claude-real-codex
npm run test:claude-real-session

These spend live Claude and/or Codex tokens.

Release Or Update Looks Stale

Run the local update flow:

npm run update:local

Then restart Claude Code. If Claude still loads an old version, run:

npm run dev:link
npm run validate:plugin

dev:link prints the marketplace and installed cache symlinks that Claude Code and Claude Desktop share.