# Codex CLI Codex CLI is the terminal-native surface of [[OpenAI Codex]]; an agentic coding tool that reads, edits, and runs code on the local machine. Built in [[Rust]] for speed, open source, and the most automation-friendly of the four Codex surfaces. It is the natural counterpart to [[Claude Code]] and [[Gemini CLI]]. It is the surface to use when the goal is scripting, scheduling, CI integration, or a fast TUI loop without leaving the terminal. ## Installation Requires a ChatGPT Plus, Pro, Business, Edu, or Enterprise plan, or an OpenAI API key. macOS, Linux, and Windows are supported natively. ```sh npm install -g @openai/codex ``` Pin a specific version when needed (helpful given the rapid release cadence): ```sh npm install -g @openai/[email protected] ``` First run; authenticate with the ChatGPT account or paste an API key. ## Key features - Interactive TUI session with project context awareness. - Approval profiles; explicit permission profiles replaced the old `--full-auto` flag (deprecated). Profiles work in both TUI sessions and MCP sandbox state. - Local code review by a separate Codex agent before committing. - Web search for fresh information during a task. - Image input (screenshots, design specs) and image generation in-CLI. - Cloud handoff; launch tasks in Codex Cloud directly from the terminal. - Scriptable via `codex exec` for automated workflows; supports `--json` for programmatic consumers, including reasoning-token usage. - Hooks; configurable in `config.toml` and stable since 0.124.0. - App-server APIs; persisted `/goal` workflows, model tools, runtime continuation, Unix socket transport. - Bedrock support; first-class Amazon Bedrock with SigV4 signing. - Plugin marketplace; remote bundles with caching since 0.128.0. ## Models GPT-5.5 is the recommended default as of April 2026. GPT-5.4 and GPT-5.3-Codex remain in the picker. For routine work and to keep token cost down, the **GPT-5.1-Codex-Mini** tier is the right choice. Switch model and reasoning level via the `/model` command. Quick reasoning controls; `Alt+,` to lower, `Alt+.` to raise (since 0.124.0). ## Configuration Config lives at `.codex/config.toml`, project- or user-level, plus `.codex/requirements.toml` for hard requirements that must be met before a run starts. Common knobs: - Default model and reasoning level. - Permission profile (the modern replacement for `--full-auto`). - Hooks; pre/post tool, pre/post commit, observed across MCP tools, `apply_patch`, and long-running Bash sessions; stable since 0.124.0. - MCP servers (stdio and remote). - Bedrock signing (AWS SigV4) for enterprise tenants. - TUI keymaps and update strategy (`codex update`). - Service tier; eligible ChatGPT plans default to "Fast" since 0.124.0. ## Recent release shape The release cadence is fast; pin if reproducibility matters. Highlights from the 0.124–0.128 line (April 2026): - **0.128.0** — `codex update`, persisted `/goal` workflows, plugin marketplace installation with remote bundle caching, external agent session import, MultiAgentV2 explicit thread caps, deprecation of `--full-auto`. - **0.125.0** — Unix socket transport for app-server clients; permission profiles round-trip across TUI, user turns, MCP sandbox state, and APIs; `codex exec --json` reports reasoning-token usage; rollout tracing covers tool, code-mode, session, multi-agent. - **0.124.0** — Quick reasoning controls (`Alt+,` / `Alt+.`); first-class Bedrock; remote plugin marketplaces; hooks marked stable; per-turn environment selection in app-server sessions. Check `https://developers.openai.com/codex/changelog/` for current details before relying on a specific feature. ## Token economy; the spike trap Codex CLI sessions can balloon fast. The bswen analysis (March 2026) on a single project surfaced these numbers: - Median context per turn ~96k tokens, p95 reaching ~200k. - Baseline overhead jumped to 21–22k tokens (up from 12–15k) after 0.106.0. - Shell tool output dominated; ~90% of all tool-output characters came from raw shell dumps (`git diff`, `rg`). - Sessions hit 100k+ tokens by turn 5–10 without compaction. ### Mitigations - **Constrain shell output**; use `git diff --stat main...feature | head -20` rather than full diffs. Pipe everything heavy through `head` / `--max-count` / `--stat`. - **Disable unused MCP servers**; each adds tool descriptors to every prompt. - **Switch to Mini for routine tasks**; reserve GPT-5.5 for hard sub-tasks. - **Compact threads manually**; use the API to summarize long sessions rather than hoping for auto-compaction. - **Be precise in prompts**; specify file paths, error strings, expected outputs. Vague prompts trigger broad searches. - **Watch baseline**; 0.106.0+ baseline grew. If a fresh session feels heavy, check the version and pin if needed. The 60–80% reduction in token cost reported in the bswen analysis came from systematic application of these, not from any single setting. ## Extensibility - **[[Model Context Protocol (MCP)]]**; third-party tool integration. - **AGENTS.md**; project agent config (AAIF format). - **[[AI Agent Skills]]**; reusable capability bundles via the open Skills standard. ## Codex CLI vs Claude Code Both are terminal-native agentic coding tools. Practical differences: - **Surface portability**; Codex CLI shares state with [[Codex App]], the IDE extension, and Codex Cloud. Claude Code shares with the SDK and IDE extensions but no desktop app. - **Engine**; Codex defaults to GPT-5.5; Claude Code defaults to Claude Opus 4.7. - **Model swap**; Codex switches between OpenAI/Bedrock variants via `/model`. Claude Code is Anthropic-first but can be proxied (e.g., via [[LiteLLM]]). - **Skills standard**; both support the open Agent Skills standard; portability between them is real. - **Pricing**; Codex is bundled into the ChatGPT subscription. Claude Code can run on subscription or API tokens. Run both. They have different failure modes and switching reveals weaknesses faster than committing to one. ## References - Documentation: https://developers.openai.com/codex/cli/ - Changelog: https://developers.openai.com/codex/changelog/ - Source: https://github.com/openai/codex - Token spike analysis (bswen, March 2026): https://docs.bswen.com/blog/2026-03-02-codex-cli-token-usage-spike/ ## Related - [[OpenAI Codex]] - [[Codex App]] - [[Codex plugin for Claude Code]] - [[Claude Code]] - [[Gemini CLI]] - [[Kimi CLI]] - [[AI Agent Harness]] - [[abtop]] - [[AgentsView]] - [[Model Context Protocol (MCP)]] - [[AI Agent Skills]] - [[Agentic AI Foundation (AAIF)]]