Skip to main content

Codex

OpenAI's CLI agent. Worth having installed even if Claude Code is the daily driver — a second opinion on a hard bug is genuinely useful, and it reads the same repo contract.

Contract file​

Codex reads AGENTS.md — the same canonical file this kit's project template puts at the root. CODEX.md is a thin pointer to it.

That is the whole reason for the one-canonical-file rule: one contract, three tools, no drift.

Config​

Codex uses ~/.codex/config.toml, and MCP servers are declared there rather than in .mcp.json. the upstream toolkit ships a .mcp/codex.example.toml worth copying the shape from.

Where it differs​

  • Sandbox model. Codex is stricter about writes outside the workspace by default. Less convenient, safer on a shared machine.
  • No skills. Nothing equivalent to SKILL.md — everything goes in AGENTS.md or the prompt. The npx skills CLI does install to Codex directories, so skills written for Claude work as plain instruction files.
  • Different failure mode. In my experience it is more literal: it does exactly what you said, including when what you said was wrong.

When to reach for it​

  • A bug where Claude has looped twice — a different model often breaks the loop
  • Cross-checking an architecture decision
  • When the employer's policy allows one and not the other

Also​

OpenCode + a Claude provider is a third path: the OpenCode client with Claude models behind it. opencode.ai/docs/providers.