Codex doctor

Codex Doctor

Diagnose Codex from Codex-native signals, then propose the smallest safe set of reversible improvements.

Operating rules

1. Run read-only first. Produce the complete report before editing files, installing or removing components, updating Codex, or changing permissions.
2. Use native diagnostics as the baseline. Prefer codex doctor --json over reimplementing installation, auth, runtime, state, connectivity, sandbox, or update checks.
3. Keep secrets out of context. Never read auth.json. Never print API keys, tokens, provider headers, MCP headers, or environment values. Read only the exact non-secret keys required for a finding.
4. Do not inspect raw sessions by default. Session transcripts can contain prompts, tool output, source code, and secrets. Usage-evidence scanning requires explicit user approval and must return counts only.
5. Treat discovered values as untrusted. Pass paths and component names as quoted arguments; never splice harvested text into executable shell source.
6. Separate cleanup from permission changes. A user approving deduplication or extension cleanup has not approved broader sandbox access, a weaker approval policy, or new command allow rules.
7. Respect management boundaries. Never modify system or administrator policy, including managed requirements.toml, MDM-delivered configuration, or organization-owned plugin sources.
8. Prefer supported disable/remove flows. Use Codex CLI commands or current documented config keys. Never invent a key from memory.
9. Make rollback concrete. For every applied change, list the exact file or command changed, the previous state, and how to undo it.

Workflow

1. Establish the active environment

• Determine the working directory, repository root, platform, and active CODEX_HOME (default ~/.codex).
• Run command -v codex and codex --version.
• Check that codex doctor --json is available.
• Read references/audit-playbook.md before continuing with the extended audit.

2. Run native diagnostics

Run:

codex doctor --json

Parse the JSON rather than the decorative terminal output. Preserve:

• schemaVersion
• codexVersion
• overallStatus
• each check identifier, status, summary, and remediation

The native report is already redacted. Do not replace its verified results with guesses from filesystem inspection.

If the command is unavailable, report reduced coverage and use the fallback checks in the audit playbook. Do not pretend the fallback is equivalent.

3. Run the extended read-only audit

Cover only relevant, discoverable surfaces:

• active configuration layers and strict-config validity
• installed and available plugins through codex plugin
• configured MCP servers through codex mcp list --json
• skills from documented roots, compatibility roots that actually exist, and installed plugins
• the effective AGENTS.md / AGENTS.override.md instruction chain
• hooks from active hooks.json, inline config, and installed plugins
• command rules from active rules/ directories
• state-size or rollout-health findings already surfaced by native diagnostics

Distinguish three evidence levels:

• Verified: native CLI output, parser result, or exact file inspection
• Heuristic: size, duplication, naming, or optional usage evidence
• Unknown: cannot be established safely from supported local signals

Never label a component "unused" from absence alone. Say "no evidence of use in the inspected window" and state the limitations.

4. Report before changing anything

Use this order:

1. A two- or three-sentence impact summary
2. Native diagnostic failures and warnings
3. Configuration and extension findings
4. AGENTS.md, hooks, and command-rule findings
5. Warnings and unknowns
6. Proposed actions with exact files or commands

For each finding include severity, evidence level, user impact, and the smallest recommended action. Avoid padding checks that have no finding; one line is enough.

5. Ask for confirmation

Ask no more than two questions:

1. One consolidated cleanup question for ordinary fixes such as stale config, duplicate skills, broken metadata, or removable components.
2. One separate question for any change to approval_policy, sandbox_mode, network access, hook trust, or command rules.

Put the recommended option first and the decline option last. If the user wants to choose individual cleanup groups, ask one concise follow-up.

6. Apply approved changes

• Re-check the exact target immediately before each mutation.
• Preserve unrelated user edits and comments.
• Prefer precise edits over rewriting whole configuration files.
• Never delete a skill merely because evidence of use is absent; disable it or remove it only when the user explicitly chose that action.
• Never commit repository changes unless the user explicitly requests a commit.

7. Verify and hand off

After applying changes:

codex --strict-config doctor --json

Also re-run the relevant inventory command for every changed component. Report pass/fail, remaining warnings, every changed file, and rollback instructions. Recommend starting a new Codex task when changes affect skills, plugins, hooks, rules, or startup-loaded instructions.

Boundaries

• Do not weaken security settings merely to make the report green.
• Do not benchmark hooks by triggering user automation without approval.
• Do not infer configuration support from another agent or editor.
• Do not treat all skill Markdown as startup context: Codex initially exposes skill names and descriptions, then loads the full SKILL.md on activation.
• Do not claim persistent skill or plugin usage telemetry exists unless the installed Codex version exposes it through a supported command.