Codex doctor debugger

Skill Xopoko/plug-n-skills/plugins/codex-cli/skills/codex-doctor-debugger

Ready-to-install skills and plugins for Codex, Claude Code, and AI coding agents: practical workflows for app delivery, architecture, research, design, and agent tooling.

Install

npx -y skills add Xopoko/plug-n-skills --skill codex-doctor-debugger

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

8 stars8 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

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.

SKILL.md

3.9 KB, 840 tokens by cl100k_base, as published. Nobody here has run it

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.