Claude Code vs Codex CLI, on the same repository

the short answer

Pick Codex CLI if you want the agent confined by the operating system and you want to be able to read the source of the thing you are running. Pick Claude Code if you want a documented hook surface, long unattended runs, and the most worn path through the subscription and tooling ecosystem. If neither of those sentences describes a constraint you actually have, run both against the same task on the same repository for a week and keep the one you reach for without thinking.

This is a fairer fight than most comparisons in this space. Unlike an editor against an agent, these two are the same shape: a command line program you start in a working directory, hand a task, and leave alone while it reads files, writes patches and runs commands. They can be scored on the same axes without the exercise being rigged. So the question becomes which axes are worth scoring, and there are three: how each decides what it is allowed to do, what each reads to learn about your repository, and what each exposes to the outside world.

approval and sandboxing, the difference you feel first

Every coding agent has to answer one question before it does anything interesting: may I run this command? There are only two families of answer, and the two tools lean on different ones.

The first family is asking. The agent proposes, you approve, and the approval is a decision made by a human at the moment of the action. It is precise, it is slow, and it degrades in a specific way: after the fortieth prompt of an afternoon you approve without reading, which turns a safety feature into a formality. The second family is confinement: the agent runs inside a boundary drawn by the operating system, and what falls outside it is not refused by policy but is simply not possible.

where each tool sits

Codex CLI's headline safety story is confinement: it runs the agent inside an operating-system sandbox and pairs that with an approval level you choose at the start of a session, from read-only up to something close to unrestricted. This is the right architecture and it is the strongest single argument for the tool. What we could not verify for this post is the current names of the levels or the exact mechanism on each platform, both of which have changed more than once, so check codex --help rather than quoting this paragraph at anyone.

Claude Code leans on asking, with structure around it. It has a permission mode chosen per session, an allow and deny list in settings so that the commands you always approve stop asking, and hooks that can refuse a tool call programmatically before it runs. That last one is the interesting part, because a hook that inspects a proposed command and exits non-zero is a policy you write once rather than a decision you make forty times.

the files each one reads

Both agents look for a markdown file in your repository that tells them how the project works, and this is the highest-return thing you can do for either of them. Claude Code reads CLAUDE.md. Codex CLI reads AGENTS.md, which has become the closest thing this space has to a shared convention, with several other harnesses reading it too.

Running both means both files exist, and the failure mode is obvious in hindsight: they drift. One says the test command is npm test, the other still says yarn test, and the agent reading the stale one wastes ten minutes and a few thousand tokens discovering it. The pattern that survives is one canonical file and one thin layer:

AGENTS.md    # canonical. Commands, conventions, architecture, the rules that matter.
CLAUDE.md    # short. "Read AGENTS.md." Then only the Claude-specific notes.

We use exactly this arrangement in our own repository, and the discipline it requires is that nothing true of the project generally is allowed to be written in the vendor file. If you find yourself explaining the build in CLAUDE.md, it belongs in the canonical one and the other agent is about to get it wrong.

what goes in it

The things an agent cannot infer in a reasonable number of tool calls: the actual test and build commands, where the seams are, which directories are generated, the conventions a reviewer will reject a diff for breaking, and the two or three things that look wrong but are load-bearing. Not a summary of the file tree, which both agents can read faster than you can describe it.

Both tools handle a long session by compacting the conversation as the window fills, and for either one that is lossy: afterwards the agent holds a summary rather than the transcript, and what was decided early is what goes first. If a fact must survive an hour, write it to a file in the repository instead of trusting it to stay in the window.

what each exposes outward

A seam is any place another program can observe or interrupt the agent. This is not a feature most people shop on, and it becomes the thing that decides everything the moment you are running more than one agent, because a fleet you cannot observe is a fleet you are guessing about.

Claude Code's hooks

Claude Code fires shell commands at named points in a session, handing each one a JSON payload on standard input: session start, prompt submit, before and after each tool call, stop, notification, permission request. A hook's exit code can block the tool call it was fired for, which makes it a policy mechanism and not only a logger. The full set of events and the payload each carries is in our hooks guide.

The rule that matters more than any individual event: every hook must fail open. A hook that errors, hangs or exits non-zero by accident is a hook that has just bricked somebody's agent, and the difference between a useful integration and an unusable one is usually whether the author thought about that on the first day.

Codex CLI

Codex CLI is configurable through its own configuration file and command line flags, and it can be driven non-interactively, which covers a large share of what people want hooks for. We could not verify a general-purpose named-event hook surface for it as of this post, and that is a statement about our checking rather than about the tool: it may well exist, and it may have shipped since. Read the repository and the changelog before you conclude either way.

Why this matters: status. Running four agents, the only questions you have are which one is waiting for you, which one is stuck, and what the whole thing is spending. Status derived from a documented event is reliable. Status scraped from terminal output is a guess that breaks the next time somebody changes a spinner.

what Codex CLI is genuinely better at

the sandbox is the product

Confinement at the operating-system level is a stronger answer to the real fear than any number of approval prompts, and it is available by default rather than as something you build yourself. If your reason for not leaving an agent alone is that you do not want to find out what it does with a shell, this is the tool that addresses that reason directly.

you can read it

Codex CLI ships as a public repository, so what it does to your machine is inspectable rather than a matter of trust, and you can file an issue against a specific line. We have not re-read its licence file for this post, so read that yourself before you fork anything or build a product on top of it. Claude Code is not distributed as readable source in the same way, and for some teams and some procurement processes that alone settles the question.

it comes with a ChatGPT subscription many people already have

Signing in with an existing ChatGPT account rather than provisioning a new API key removes a step and, at a lot of companies, an approval. The cheapest tool is often the one already inside a subscription somebody has already expensed, and that is a real advantage rather than an accounting footnote.

a different model, which is the underrated reason to have it

Two agents from two vendors disagree in useful ways. An agent reviewing its own diff agrees with itself; a different model reading the same diff cold does not, and the disagreement is where the bugs are. That is the whole argument in using a second agent to review the first, and it is the most reliable reason to have both of these installed regardless of which you prefer.

it is quieter

This is taste rather than a capability, so treat it as one person's preference: Codex CLI tends to narrate less while it works. Some people find that calmer and some find it opaque. It is worth ten minutes of your own attention to find out which sort you are, because it is the thing you will notice every single day and no feature table will ever contain it.

what Claude Code is genuinely better at

the hook surface

Covered above and it is the biggest one. A documented event stream with blocking exit codes means status lights, audit logs, spend meters and policy checks are things you can build this afternoon instead of things you wait for a vendor to ship. Every serious multi-agent tool that shows reliable per-agent status is built on this, ours included.

long unattended runs and a mature subagent story

Claude Code is comfortable being left alone for a long time, and it can spawn subagents to handle a search or a review inside its own run without spending the parent's context on it. If the work you want done is one long task rather than twenty short ones, this is where the difference shows.

usage reporting you can act on

It reports token usage in a form that can be read and priced while the session is still running, and it keeps the four kinds of token apart: fresh input, cache write, cache read and output. That distinction is not pedantry, it is the difference between a right answer and one that is wrong by a multiple, because a long coding session is overwhelmingly cache reads. We measured it in what Claude Code actually costs.

the ecosystem around it

More third-party tooling targets Claude Code than any other terminal agent right now, so the integration you want probably exists, and the Reddit thread describing your exact problem probably exists too. That is a network effect rather than a technical merit, and it is worth real money in time not spent.

the permission model is finer grained

Permission modes, per-command allow and deny lists, and hooks that can refuse a specific tool call give you a policy that fits the shape of your repository rather than one boundary around the whole process. Confinement is stronger; this is more precise. Ideally you would have both, and neither tool gives you both today.

running both on one repository

The most common real answer is that you end up with both installed, and at that point the only question that matters is how to keep them from destroying each other's work. The answer is a directory each, and it is not optional.

cd ~/code/myapp

git worktree add ../myapp-claude -b agent/claude-api
git worktree add ../myapp-codex  -b agent/codex-schema

# two shells, each started inside its own directory
cd ../myapp-claude && claude
cd ../myapp-codex  && codex

# later, after each branch has been read by a human
git worktree remove ../myapp-claude

Two agents in one checkout will overwrite each other silently, because neither can see what the other has in flight, and the loss shows up as a change that was there an hour ago and is not there now. A worktree is a second checkout on its own branch sharing one object database, so it is cheap and everything committed inside it is already in the same repository. The longer version, including the ways it still goes wrong, is in git worktrees for AI agents, and the three-agent walkthrough is in running Claude Code, Codex and Grok together.

Three things people get wrong on the first attempt:

• Splitting by task instead of by file. Two agents told to work on different features will still both edit the router. Split by directory, decide the merge order before anything starts, and put dependencies first: schema, then the code that uses it, then the interface.
• Letting the two markdown files drift. One canonical AGENTS.md, a thin CLAUDE.md pointing at it. Anything else is two descriptions of one project that agree only on the day you wrote them.
• Not watching combined spend. Two agents is two burn rates, and neither terminal shows you the other one. Whether that matters depends on whether you are on a subscription or an API key, which is the point of setting a token budget.

If the fleet gets past three and the tracking is the problem rather than the agents, that is a different category of tool. Ours is one of them: Skribbl runs both of these CLIs as real terminals on a canvas and meters Claude Code, though not Codex, because Codex does not report usage back in a form we will price. It is macOS on Apple Silicon only, which the download page says before it asks you for anything. Several of the alternatives on our comparison page are free and open source, and that is worth knowing before you spend anything.

which should you pick

Pick Codex CLI if the thing standing between you and leaving an agent alone is not trusting it with a shell, or if reading the source of your tools is a requirement rather than a preference, or if a ChatGPT subscription is the budget you already have.

Pick Claude Code if you intend to build anything around the agent: status lights, audit logs, spend tracking, a policy that blocks a class of command. The hook surface is the reason, and it is a large reason. Also pick it if your work is long single tasks rather than many short ones.

Install both if you can afford to, and use the second one as a cold reader of the first one's diffs. This is the cheapest quality step available in the whole category, because review is mostly input tokens and input is the cheap end of every rate card.

Do not pick on model quality. Not because it does not matter, but because it is the fastest-moving variable here, any ranking published today is wrong within a quarter, and we have no measurement of our own worth putting in front of you. What will still be true next year is the shape of the approval model, the seams each exposes and how each behaves when you are not watching, which is why this post is about those and not about a leaderboard.

common questions