What Is Codex CLI and When Should You Use It?

Q: Can I run Codex CLI and Claude Code on the same project?

Yes. They use different instruction files, `AGENTS.md` and `CLAUDE.md`, so they will not fight over configuration. Give them one shared source of truth and import it into both, or the two files will drift apart within a fortnight.

Q: Which model should I pick in Codex CLI?

Start on `gpt-5.6-terra` for everyday work and move up to `sol` only when a task genuinely stalls. The message limits differ by more than tenfold across the family, so defaulting to the flagship is the fastest way to run out of usage before lunch.

Last updated: September 2026

Codex CLI is OpenAI's coding agent that runs locally in your terminal. You point it at a project, describe what you want, and it reads files, edits code, and runs commands on your machine inside a sandbox you control. It is free to install, works with a ChatGPT plan or an API key, and it is the closest direct competitor to Claude Code.

The short version

It is a terminal agent, not an autocomplete. OpenAI's own description is blunt: "Codex CLI is a coding agent from OpenAI that runs locally on your computer." It edits files and runs commands rather than suggesting lines in an editor.
Your ChatGPT subscription probably already covers it. If you pay for ChatGPT Plus, you can run codex login and start today without touching an API key or adding a bill.
Pick it over Claude Code for native Windows work, open-weight models, or if your team already standardised on AGENTS.md. Otherwise the two are close enough that habit matters more than features.

I should say plainly where I stand. My curriculum teaches Claude Code, and I use it daily. That is a bias, not a secret, so I have kept everything below to differences you can verify in either tool's documentation rather than to which one feels better.

What does Codex CLI actually do on your machine?

It runs as a chat session inside your terminal, with your project as its working directory. The docs summarise the job as "Inspect, edit, and run code from your terminal." In practice you describe an outcome, it reads the relevant files, proposes and makes edits, runs commands like your test suite, and reports what happened.

Installation is one line. On macOS and Linux it is curl -fsSL https://chatgpt.com/codex/install.sh | sh. On Windows it is a PowerShell one-liner fetching https://chatgpt.com/codex/install.ps1. It is also on npm as @openai/codex and on Homebrew as a cask. Then codex login opens a browser flow that ties usage to your ChatGPT plan, or you can authenticate with an API key and pay per token instead. codex logout switches between the two.

The part worth understanding before you run it on anything real is the permission model, because it is two separate dials and people conflate them.

The first dial is the sandbox, which decides what Codex is physically able to touch. read-only lets it look but not change anything. workspace-write is the default and lets it read, edit, and run commands inside your working directory while blocking network access. danger-full-access removes the guardrails entirely, and the name is doing you a favour.

The second dial is the approval policy, which decides when it stops to ask you. The default, presented as "Auto", is on-request: per OpenAI's security documentation, "Codex can read files, make edits, and run commands in the workspace. Codex requires approval to edit outside the workspace or to access network." untrusted asks far more often. never stops asking altogether, which is only safe because the sandbox still caps what it can reach.

That separation matters. Turning off approvals does not turn off the sandbox. People who get burned usually loosened both at once because they read them as a single setting.

For scripting, codex exec runs a prompt non-interactively and --json emits a machine-readable event stream, which is what you would wire into CI. codex resume --last picks a session back up.

Which models does Codex CLI run, and what do they cost?

The current family is GPT-5.6, generally available since 9 July 2026. Configuration lives in ~/.codex/config.toml, and a project-level .codex/config.toml loads only when you trust the project.

Model	Best for	Notes
`gpt-5.6-sol`	Complex coding, computer use, research	Flagship. The interface shows it as the recommended default
`gpt-5.6-terra`	Everyday work	Balanced cost and capability
`gpt-5.6-luna`	High-volume, simpler tasks	Cheapest, and by far the highest message limits
`gpt-5.3-codex-spark`	Real-time coding	Research preview, Pro tier

One date to put in your calendar: gpt-5.4 and gpt-5.4-mini retire from Codex on 31 August 2026. If you pinned either in a config file or a CI job, it stops working, and the migration path is terra and luna respectively. This is the kind of thing that breaks a pipeline quietly on a Monday.

You also get reasoning effort tiers: Low, Medium as the default, High, Extra High, Max, and Ultra, which automatically delegates to subagents for parallel work.

On cost, ChatGPT Plus is $20 a month, Pro is $100 for five times the limits or $200 for twenty times, and Business is $20 per user per month billed annually. Cheaper tiers exist below Plus with more limited access, and the sign-in documentation and the pricing pages do not describe those limits identically, so check the current pricing page rather than trusting any article, including this one, on where the floor sits.

Limits are counted as local CLI messages per rolling five-hour window, and the spread between models is enormous. On Plus you get roughly 10 to 100 messages on Sol, 25 to 200 on Terra, and 250 to 2,000 on Luna, and Business Standard now carries the same allowance rather than a reduced one. That range is the real lesson: model choice changes your usable volume by more than an order of magnitude, which is the same trap I wrote about in what Claude Code pricing does not tell you.

How does Codex CLI compare to Claude Code?

Close enough that I would not switch a working setup on features alone. But there are four differences that are genuine, checkable, and might decide it for you.

Windows support runs the opposite way in each tool. Codex has a native Windows OS-level sandbox. Claude Code's sandbox documentation is explicit that it "runs on macOS, Linux, and WSL2. Native Windows is not supported." Claude Code itself installs and runs on Windows natively; it is the sandbox specifically that wants WSL2, which is why I wrote a separate guide to setting it up on Windows and WSL. If you are on Windows, refuse to use WSL, and want OS-level sandboxing, Codex wins outright.

Project instructions use different files, and only one of them is an open convention. Codex reads AGENTS.md, which Cursor, Copilot and Gemini CLI also read. Claude Code reads CLAUDE.md and does not read AGENTS.md natively; the documented workarounds are importing it with @AGENTS.md from inside your CLAUDE.md, or symlinking the two. If you are a mixed-tool team, AGENTS.md is the file that travels. If you want the detail on the other side of that fence, I covered what goes in a CLAUDE.md file separately.

Codex layers those files from a global ~/.codex/AGENTS.md down through your Git root to your working directory, capped at 32 KiB by default. The precedence rule is worth memorising because it is the opposite of what people assume: "Files closer to your current directory override earlier guidance because they appear later in the combined prompt."

Claude Code has three things I could not find a Codex equivalent for. A branded Plan Mode for read-only exploration before any edit. /rewind, which restores the conversation and your code to an earlier checkpoint. And /usage, which attributes spend by skill, subagent, plugin and individual MCP server. That last one sounds like a nice-to-have until the first time an agent quietly burns a week of limits and you need to know which part did it.

Codex has an --oss flag for pointing the CLI at local open-source model providers. I found no equivalent in Claude Code, whose non-Anthropic paths are the major clouds. If running open weights locally matters to you, that is a real gap.

What is not a difference, despite what comparison posts will tell you: both run on Amazon Bedrock, both ship first-party GitHub Actions and automated pull request review, both have a skills system built on SKILL.md files with progressive disclosure, and both have subagents. If you want the full head-to-head on output quality rather than features, I ran three models against the same build and the results were not what the benchmarks predicted.

When should you actually use it?

Use Codex CLI if you already pay for ChatGPT and do not want a second subscription. That is the honest number one reason, and it is a good one. Marginal cost of zero beats a marginally better tool at $20 a month for most people learning this.

Use it if you are on native Windows without WSL, if your team has standardised on AGENTS.md, or if you need local open-weight models.

Use Claude Code if you want the checkpoint and rewind safety net, or per-component usage attribution, or if you are following a curriculum built around it, which includes mine.

And use whichever one you will actually open. The students who make progress are not the ones who picked correctly. They are the ones who picked, then spent forty hours in the tool learning where it lies to them. Both of these agents are good enough that the second decision matters far more than the first.

Frequently Asked Questions

Is Codex CLI free?

The tool itself is free to install. Running it is not: you either use an included allowance from a paid ChatGPT plan or pay per token with an API key. Free and entry-level tiers exist with more limited access.

Is Codex CLI the same as the old OpenAI Codex model?

No, and the name collision causes real confusion. The original Codex was a code-completion model retired years ago. Today's Codex is a family of agent products, of which the CLI is one surface alongside an IDE extension, a cloud version, the ChatGPT desktop app, and iOS.

Do I need to know how to code to use Codex CLI?

You need to be able to read what it produces well enough to tell when it is wrong. It will happily run commands on your machine. Starting in read-only sandbox mode while you learn is the sensible move.

Can I run Codex CLI and Claude Code on the same project?

Yes. They use different instruction files, AGENTS.md and CLAUDE.md, so they will not fight over configuration. Give them one shared source of truth and import it into both, or the two files will drift apart within a fortnight.

Which model should I pick in Codex CLI?

Start on gpt-5.6-terra for everyday work and move up to sol only when a task genuinely stalls. The message limits differ by more than tenfold across the family, so defaulting to the flagship is the fastest way to run out of usage before lunch.

Not sure which agent belongs in your week?

The honest answer for most people is that the tool matters less than having someone point out the three habits costing you the most time in it. That is a conversation, not a comparison table. Book a free 15-minute Discovery Call and bring whichever agent you are already using.

Written by Michael Murr for AI Tutor Code: private 1-on-1 online tutoring for professionals learning Python, AI tools, Data Science, ML, and LLM engineering. 200+ students taught, 3,000+ hours delivered.