Codex CLI
OpenAI Codex CLI
- codex
codex exec with a native read-only sandbox. TOML config, comments kept on edit.
- Invoke
- 4 of 6 · official
- Models
- native listing
- MCP
- toml · standard
- Agents file
- ~/.codex/AGENTS.md
Access
- Get
getHarness("codex") - CLI
harnesses paths codex --json - Trycodex in the explorer
Codex keeps its configuration in TOML, and people write comments in TOML. addMcpServer and removeMcpServer therefore edit config.toml surgically instead of parsing and serializing it again, and the comments survive. The project file is searched from the working directory up to the .git boundary, which the note on that entry says because it is not what the path alone suggests.
codex exec --sandbox read-only is a sandbox the CLI enforces, so readOnly: true is a real mode here. codex exec cannot switch its tools off, so there is no advisor; ask for one and the error tells you to retry with tools: true. Detection is by project markers only, AGENTS.md among them, which is why a directory with both a CLAUDE.md and an AGENTS.md detects as nothing rather than as Codex.
listModels reads codex debug models, the catalog Codex picks from itself. A debug command as an API? Not pretty, but it's the only list Codex prints. So the note pins the version it was checked on. A shape the parser doesn't know throws instead of guessing. Models Codex hides from its own picker stay hidden here too. There's no filter in the CLI, so search matches ids locally. Each model also brings its display name, which is how gpt-daybreak-blue-latest turns out to be Daybreak Blue.
One catch with model. Codex wants the bare slug, and openai/gpt-5.5 gets a 400 from OpenAI. That's why modelSelector leaves the provider off.
Capabilities and invocation
- mcp: yes
- vision: yes
- audio: no
- video: no
- tools: yes
- streaming: yes
Binary codex, evidence official. Non-interactive exec subcommand; add --json for structured output. Model selection appends --model {model}.
- advisor{}rejected
- advisor · json{ structured: true }rejected
- read-only{ readOnly: true }
exec --skip-git-repo-check --sandbox read-only {prompt} - read-only · json{ readOnly: true, structured: true }
exec --skip-git-repo-check --sandbox read-only --json {prompt} - agent{ tools: true }
exec --skip-git-repo-check {prompt} - agent · json{ tools: true, structured: true }
exec --skip-git-repo-check --json {prompt}
Model listing runs codex debug models, and a filter matches the ids locally. Prints the model catalog as JSON, refreshed from OpenAI unless --bundled, with no filter of its own; only models Codex shows in its picker are kept. It lives under debug, so the shape can move between releases; verified with 0.160.0.
Paths
Templates as the registry stores them. ~, ${HOME}, ${TMPDIR} and %VAR% expand in resolve(); entries tagged with a platform are dropped on the others. Open in the explorer to see them expanded for a home directory of your choice.
config
~/.codex/config.toml.codex/config.tomlSearched from cwd up to project root (.git boundary).
/etc/codex/config.toml
sessions
~/.codex/sessions/Session rollouts in JSONL format, organized by date.
~/.codex/history.jsonlCommand history.
~/.codex/state_5.sqliteSQLite state database for threads and agent state.
instructions
AGENTS.mdAGENTS.override.mdLocal override, takes precedence over AGENTS.md.
~/.codex/AGENTS.mdGlobal user-level instructions.
~/.codex/AGENTS.override.mdGlobal override, takes precedence over global AGENTS.md.
skills
.codex/skills/.agents/skills/~/.codex/skills/Deprecated, use ~/.agents/skills/ instead.
~/.agents/skills//etc/codex/skills/
commands
~/.codex/prompts/Deprecated Markdown prompts invoked as /prompts:name. Top-level files only; use skills for shared prompts.
promptTemplates
~/.codex/prompts/Deprecated Markdown prompts invoked as /prompts:name. Top-level files only; use skills for shared prompts.
Empty
hookstempThat is not the same as the feature being missing.
Env overrides
Variables the harness reads to move a root. The path is the default while the variable is unset; resolve() applies a set one to temp.
CODEX_HOME~/.codexconfig · sessions · instructions · skills · commands · promptTemplates
MCP servers
~/.codex/config.tomluser · toml · standard · mcp_servers.codex/config.tomlproject · toml · standard · mcp_servers
Detection
envVars
None. Detection is by project markers only.
projectMarkers
- .codex
- AGENTS.md
- AGENTS.override.md
- .agents/skills
Persistence
- TOML - Configuration files. (official)
- JSONL - Conversation transcripts. (official)
- SQLite - Thread and agent state. (official)
syncAgentsFiles links ~/.codex/AGENTS.md to the master bundle.