Codex CLI: OpenAI's Terminal Coding Agent, Explained

What Codex CLI is

Codex CLI is OpenAI's coding agent that runs on your machine. You start it in a repository, describe a task, and it inspects files, proposes edits, runs commands, and reports back in the terminal. The client is open source under Apache-2.0 at openai/codex, so the harness is inspectable even though the models are not.

The same agent shows up in four places, and they share configuration:

The CLI is the surface this cluster covers. Configuration written in ~/.codex/config.toml applies to the CLI, the desktop app, and the IDE extension on the same host, so setup work carries across all three.

The two safety layers

Codex separates what the agent can technically do from when it must stop and ask. Those are different controls, and conflating them is the usual reason a run behaves unexpectedly.

• Sandbox mode sets the technical boundary: read-only, workspace-write, or danger-full-access. The default is workspace-write, which allows edits inside the workspace and leaves network access off.
• Approval policy sets the interruption rule: on-request pauses when the agent wants to leave the sandbox or use the network; never removes the prompt entirely.

The "Auto" preset documented by OpenAI is --sandbox workspace-write --ask-for-approval on-request: ordinary edits and commands proceed, escalations ask. read-only plus on-request is the combination for planning and review work where the tree must not change. --dangerously-bypass-approvals-and-sandbox (alias --yolo) removes both layers and should be treated as a container-only escape hatch.

Inside a writable workspace, .git/, .agents/, .codex/, and .aws/ stay read-only in many environments. That is why git commit can still trigger an approval even when file edits do not. The configuration reference lists the modes, policies, and network keys in full.

Where Codex wins

• The terminal loop is the product. Inspect, plan, edit, run tests, and resume in one session with codex resume; no IDE round-trip.
• Scripted runs are first-class. codex exec runs without a TUI, prints only the final message to stdout, streams progress to stderr, and can emit JSON Lines with --json. That is a clean fit for CI and pre-merge checks.
• Review is built in. codex review --uncommitted reports prioritized findings against your checkout without modifying the working tree. It is a separate mode from asking the agent to "look at the diff."
• MCP configuration is shared. Servers added with codex mcp add are available to the CLI, desktop app, and IDE extension on that host.
• The harness is open. Apache-2.0 licensing means you can read exactly how instructions, approvals, and tool calls are assembled.

Codex also loads skills — reusable procedures like a review pass or a test loop, stored as instruction folders and pulled in only when a task needs them. The site's agent skills collection covers the format and the packs worth installing.

Where Codex loses

• Plan access and API access are not equivalent. Signing in with ChatGPT ties usage to workspace permissions and plan entitlements. An API key bills at standard API rates and some features that depend on ChatGPT workspace access are limited or unavailable.
• Network is off by default. Dependency installs and package fetches fail in workspace-write until you enable [sandbox_workspace_write] network_access or approve the escalation. That is a safety default, not a bug, but it surprises people on the first run.
• Subagents cost more. Each subagent does its own model and tool work, so a delegated run consumes more tokens than a single-agent run of the same task.
• Windows has a second sandbox story. The preferred path is MXC; the legacy elevated mode is a fallback with its own setup requirements.

Against Claude Code, the practical split is model family and harness style: Codex runs OpenAI models and exposes exec/review/cloud as distinct commands, while Claude Code is built around Anthropic models and its own hook and configuration surface. Against OpenCode, the split is provider breadth: OpenCode is designed to switch among many providers mid-session, while Codex is an OpenAI-first client. The tool comparison covers the full matrix.

What a session looks like

A typical bounded task moves through five visible states: the agent reads files, proposes a plan, edits, runs a command, and reports. The terminal shows the commands and diffs as they happen; you can interrupt a turn without killing the session and redirect the work in the same chat. codex resume reopens a saved chat from the current repository, and codex exec runs the same loop without a UI when you need it in a pipeline. That continuity is the main reason people keep the CLI open beside an editor: the session carries context that a fresh chat does not.

Start here

1. Getting started — install, authenticate, trust a repository, and run a first task.
2. Prompt engineering — the instruction chain and the four prompt contracts that hold up.
3. Configuration — precedence, sandbox modes, approval policies, profiles, and MCP servers.

If you are deciding whether Codex is the right harness at all, read Codex as reviewer first. It is the workload where the review/exec split matters most.

Sources

• Codex CLI
• openai/codex README
• Models
• Agent approvals and security