OpenAI Codex CLI, a real operator's guide

Every time OpenAI ships something new in the coding space, my inbox fills up with the same question: "should I switch?" The honest answer, as of mid 2026, is no. But you should absolutely add Codex CLI to your toolbelt. It does one thing better than anything else, and if you are already paying for ChatGPT Plus, the marginal cost is zero.

This is not a walkthrough of every flag. It is a field guide to installing it, using it without regret, and knowing when to reach for it instead of Claude Code or Cursor.

What Codex CLI actually is

Codex CLI is OpenAI's open-source terminal coding agent. You install it with npm, run codex in a project directory, and get a REPL-style prompt. You describe a task. It reads the code, plans, edits files, runs commands, iterates.

The key thing to internalize: it edits your files directly. Not a preview pane, not a diff you approve line by line. Your working tree changes. Which is exactly the point, and exactly why the safety story matters.

Install, in ninety seconds

1. You need Node 18 or newer. Check with node --version. On Mac, brew install node. On Windows, WSL is the sane path.
2. npm install -g @openai/codex. You can also use brew install codex on Mac or grab a native binary from the GitHub releases.
3. codex. First run, it asks you to sign in. Two options: use your ChatGPT Plus, Pro, or Team account, or paste an OpenAI API key. Sign-in mode is included in the subscription. API mode is pay-per-token.
4. Change into a project directory. Run codex again. You are in.

The three approval modes, in plain English

• suggest. Codex proposes every edit and every command. You approve. Safe. Slow. Good for the first hour.
• on-request. Codex runs safe operations (reads, edits inside the sandbox) automatically. It asks before running shell commands or reading files outside the project. This is the right default for real work.
• full-auto. Codex runs everything without asking. Do not use this outside a sandbox, a container, or a throwaway branch. Do not use it on main.

How to actually use it

Codex CLI shines when the task has a shape. Not "make this better." Not "add a feature." Specifically:

1. Failing test to green.
2. Codemod-style refactor across the repo.
3. Migrating a file or module from one library to another.
4. Writing docs for existing code.
5. Bulk find-and-fix across many files with a rule you can describe.

The pattern I use for anything non-trivial:

1. git checkout -b codex/whatever. Fresh branch. Always.
2. Write the task as a short markdown file. Paste it into Codex. Two to eight bullet points, the files involved, the success criteria.
3. Let it work. Watch the tool calls. Do not interrupt unless it is clearly heading somewhere wrong.
4. When it says done, run your tests yourself. Do not trust the "tests pass" claim without seeing the output.
5. Read the diff. Not skim, read. Push back or ask it to explain any change that surprises you.
6. Commit. Push. Open the PR. Let CI weigh in.

Where Codex CLI beats Claude Code

• Tighter GPT model integration. If your org is standardized on OpenAI, using Codex CLI keeps your billing, your usage tracking, and your model access in one place.
• Native binary. The Rust-based native binary is notably snappier than the Node-only alternatives. On big repositories, the startup difference is noticeable.
• Cheap bulk tasks. Drop to gpt-5-mini for bulk find-and-fix work and the per-token cost is a fraction of Claude Sonnet. If you are running Codex over hundreds of files in a codemod, this matters.
• Free with a subscription you probably already have. If you pay for ChatGPT Plus, Codex CLI is included at generous limits. That is a strong price point.

Where Claude Code still wins

• Long-context reasoning. Claude tends to hold twenty-file mental models more coherently. On big refactors, the finish rate is better.
• Following complex specs without drifting. This is subjective and it changes model by model, but as of this writing, Claude is stickier to the original intent.
• Ecosystem maturity. Claude Code has a larger community, more plugins, more MCP integrations, more shared prompt patterns. Codex CLI is catching up fast, but it is catching up.

How not to wreck main

Every horror story I hear about agent-edited codebases follows the same pattern: someone ran an agent in full-auto on main, went to lunch, came back to a rewritten codebase, and now the tests pass but nothing works. Four rules that make this impossible:

1. Never on main. Always a branch. Non-negotiable.
2. Never in full-auto outside a container. Run full-auto inside Docker, a devcontainer, or a fresh VM. Never on your working machine.
3. CI has to pass before merge. Codex saying "tests pass" is not enough. Your real CI has to be green.
4. Code review by a human before merge. Even if the human is you an hour later, with fresh eyes. Agents are confident when they are wrong.

Configuration that pays for itself

Open ~/.codex/config.toml. Add:

• approval_mode = "on-request". Default for all sessions.
• model = "gpt-5-codex". The right default in 2026. Drop to gpt-5-mini for bulk tasks by passing --model gpt-5-mini at launch.
• A project-scoped AGENTS.md at your repo root that lists the conventions of the codebase: test framework, lint rules, directory layout, "never edit these files." Codex reads it automatically. It is the single highest-leverage config change you can make.

The workflow I actually run

Cursor for exploration and small edits. Claude Code for long refactors that need reasoning discipline. Codex CLI for bulk work, codemods, and anything I want to run cheaply at scale. All three, same repo, different jobs.

The teams that pick one and reject the others are usually optimizing for a bill that does not matter (forty dollars a month combined) at the cost of a productivity gap that does (hours per week). Use all three. Pick the right one for the task. Move on.

Common questions

If you want the deeper build

Codex CLI (and Claude Code, and Cursor) are the front door. What is behind the door is the harder work: agents that touch production, tools that need permission models, evals that catch regressions before your customers do. That is what I build for teams. See custom AI agent development or the Claude Code vs Cursor breakdown.