OpenAI released Codex CLI in April 2025 and it’s been quietly maturing since. If you’ve heard of it but haven’t tried it — or you’re a Claude Code user wondering whether to switch — this is the practical breakdown.

Codex CLI is a terminal-based AI coding agent. You run it from your shell, describe what you want, and it reads your codebase, writes and edits files, executes shell commands, and runs tests. It’s in the same category as Claude Code, which Anthropic shipped around the same time, and the competition between them has pushed both forward faster than either would have moved alone.

The three execution modes

The thing that distinguishes Codex CLI’s design from a basic AI coding assistant is its explicit permission model. When you run a session, you choose from three modes:

Suggest mode is the most conservative. Codex reads your codebase, reasons about your request, and produces a proposed diff and a list of commands — but it doesn’t execute anything. You review the proposal and apply it yourself if you’re happy with it. Think of it as a very capable pair programmer that stops before touching anything.

Auto-edit mode lets Codex read and write files automatically, but still requires your confirmation before running any shell command. Writes go ahead; executions wait for approval. This is the default for most developers and balances useful automation with the ability to catch commands before they run.

Full-auto mode is what it sounds like. Codex reads, writes, and executes without asking — running tests, installing dependencies, making commits, the whole thing. OpenAI runs full-auto operations in a sandboxed network environment to limit the blast radius, but this mode does require you to trust the model’s judgment about what to execute. Most developers use it for well-scoped, clearly defined tasks where the risk of an unexpected command is low.

The modal design is one of the more thoughtful things about Codex CLI. You pick the level of autonomy appropriate to the task, rather than being at the mercy of a single agent behaviour.

How it works in practice

Setup is straightforward — npm install -g @openai/codex and export OPENAI_API_KEY=your_key. Running codex in a project directory opens an interactive session. You describe what you want, Codex reasons about it (the thinking output is streamed to the terminal, which is useful for understanding what it’s doing), and it acts according to your chosen mode.

The codebase context window is one of Codex CLI’s genuine strengths. It uses a combination of filesystem traversal, .gitignore awareness, and a content-hashing approach to efficiently include relevant files in its context without naively shoving everything in. For large repositories this matters — the context it receives tends to be well-targeted rather than a random sample.

It handles multi-step tasks reasonably well. “Write a test suite for the auth module, run it, and fix any failures” is a task it can execute in full-auto mode without hand-holding, provided the test infrastructure is already in place. Where it gets unstuck — like most AI coding agents — is when a task has implicit dependencies that weren’t mentioned, or when the right approach requires understanding architecture decisions that aren’t evident from the code alone.

How it compares to Claude Code

If you’re already using Claude Code, the honest comparison is: they’re close, and which you prefer often comes down to smaller differences than the marketing would suggest.

Codex CLI uses GPT-4o (or o3 on the research subscription tier). Claude Code uses claude-opus-4 and claude-sonnet-4 variants. Both are capable models for code — the differences are visible but not dramatic for most everyday tasks.

Where Claude Code edges ahead, in most developers’ experience, is on long-context reasoning and multi-file refactoring. When a task requires understanding relationships across a large codebase and making a consistent change throughout, Claude Code’s context handling tends to be more reliable. It’s also slightly less prone to “solving” the stated task in a way that technically works but misses the intent.

Where Codex CLI holds its own is on agentic reliability in the full-auto mode — the sandboxed execution environment and the explicit permission model mean it’s somewhat less likely to take an unexpected action that causes problems. The suggest mode is also useful in contexts where you want AI assistance without giving the agent write access to your repository.

Pricing is similar. Both bill on API token consumption. Both offer interactive and non-interactive (scripting) modes.

The real question

If you’re on neither, try both. Both have free tiers sufficient to evaluate them on a real project. The best workflow for most developers right now involves having a preference but knowing both well enough to reach for the right tool — Claude Code for long refactors and architecture conversations, Codex CLI for well-scoped automation tasks where the modal execution control is useful.

If you’re already committed to one, the productivity cost of switching is probably not worth it until there’s a more decisive capability gap. Both are good and both are improving rapidly. The competition between them is, to be honest, good for everyone using either.