Field guide / 10 min
Diagnose Codex, inspect features, and generate completions
Use observable inventories before changing configuration or shell startup files.
Codex provides doctor for layered installation and runtime health, features for staged feature state, completion for shell integration, and debug utilities for targeted evidence such as the bundled model catalog. Start with read-only inspection, preserve version context, and review generated or diagnostic output before placing it in tickets or startup files.
Verified terminal sequence
- $
codex doctor --summary - $
codex features list - $
codex completion zsh > /tmp/_codex - $
codex debug models --bundled
Working principles
Record the release first
Feature stages, output fields, and supported shells can change. Pair every diagnostic with codex --version.
Inspect before mutate
List effective feature state before enabling or disabling one, and generate completion output before sourcing it.
Share diagnostics carefully
Reports can include paths, repository names, and configuration clues. Review and redact before external sharing.
Field procedure
- 01
Establish identity
Resolve the active executable and version so the report cannot be confused with another installation.
- 02
Run layered diagnostics
Use doctor summary first, then inspect the first failing installation, auth, config, Git, runtime, terminal, or thread layer.
- 03
Inspect feature state
Run features list and note each feature’s stage and effective value before any config mutation.
- 04
Generate shell completions
Choose bash, elvish, fish, powershell, or zsh, write output to a temporary file, inspect it, then integrate it according to that shell.
- 05
Use debug narrowly
Run a specific debug subcommand only for the evidence needed; do not publish broad dumps by default.
PASS / FAIL
Acceptance checklist
- Version and executable are recorded.
- The first failing diagnostic layer is addressed first.
- Feature changes name one exact feature.
- Completion output matches the active shell.
- Shared reports are reviewed for sensitive paths.
WATCH / REJECT
Failure patterns
- Editing several config layers before reading doctor.
- Enabling experimental features by guesswork.
- Appending generated shell code without inspecting or versioning the setup.