| name | codex-doctor-debugger |
| description | Use when diagnosing Codex CLI install, config, auth, runtime, feature flags, sandbox denials, debug models, prompt input, app-server, remote-control, remote websocket/unix connections, or local Codex health failures. |
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.
