Codex Doctor And Debugger

Bundled commands use $PLUGIN_ROOT ($env:PLUGIN_ROOT in PowerShell; same path suffix) for the plugin root. Set it once: use the host's plugin-root variable when defined (Claude Code: PLUGIN_ROOT="$CLAUDE_PLUGIN_ROOT"), otherwise the absolute path of this plugin's root directory.

Use this skill when Codex CLI itself is failing or unclear: installation, config, auth, runtime health, feature flags, sandbox denials, debug model catalog, app-server transports, remote-control daemon, remote connection errors, or local environment inconsistencies.

Inspect First

Start with cheap, non-mutating commands:

python3 "$PLUGIN_ROOT/scripts/codex_cli_inspector.py" --commands doctor debug sandbox features app-server remote-control --json
codex doctor --summary --ascii

Use machine-readable doctor output when automation needs to classify issues:

codex doctor --json

Do not paste raw doctor output into chat if it contains local paths, config fragments, or environment details that are not needed. Summarize issue names, counts, and actionable rows.

Diagnostic Lanes

Install, Config, Auth, Runtime

Use codex doctor --summary --ascii first. Expand only when the summary points to a specific area:

codex doctor --all --ascii
codex doctor --json

If config parsing is suspect, run the target command with --strict-config to surface unsupported fields for that CLI version.

Feature Flags

Read before writing:

codex features list

Use codex features enable <feature> or codex features disable <feature> only when the user explicitly asks to change a flag or the issue clearly requires it. Report any config file mutation.

Sandbox

Use sandbox commands to reproduce permission failures without launching a full agent session:

codex sandbox -C "$PROJECT" --log-denials -- <command> <args>
codex sandbox -C "$PROJECT" --permissions-profile <name> -- <command> <args>

On macOS, --log-denials can help identify blocked paths or sockets. Keep allowed Unix socket paths explicit:

codex sandbox -C "$PROJECT" --allow-unix-socket ./tmp/socket -- <command>

Debug

Use debug commands for local model/config visibility:

codex debug models
codex debug prompt-input
codex debug app-server --help

Treat debug output as potentially sensitive because it can include model, config, prompt-input, or environment-derived data.

App Server And Remote Control

codex app-server and codex remote-control are experimental surfaces. Use them only for app/IDE integration, remote TUI, protocol generation, or daemon debugging.

Prefer loopback or Unix socket transports. Do not bind WebSocket listeners to non-loopback interfaces without explicit security requirements and token setup.

Examples:

codex app-server --listen unix://
codex app-server --listen ws://127.0.0.1:0 --ws-auth capability-token --ws-token-file "$TOKEN_FILE"
codex remote-control --json start
codex remote-control --json stop

Safety Boundaries

• Do not weaken sandbox, approvals, hook trust, feature flags, managed config, or app-server auth just to make a command pass.
• Do not expose bearer tokens, token file contents, shared secrets, config secrets, cookies, or auth artifacts.
• Do not start persistent daemons or listeners unless the user asked for them, and tell the user how to stop them.
• Do not delete config, sessions, caches, plugins, or logs during diagnosis without explicit approval.

Completion Standard

Report the diagnostic lane, commands run, exact issue names or error text, version/help facts used, any config or daemon state changed, and the smallest next repair or verified healthy state.