Claude Code or Codex — decision card · Resource

Open this card when you have one specific task in front of you and you're deciding whether to hand it to Claude Code or Codex. It doesn't settle which tool is better in general, because for most work they do the same things. It helps you match the agent to this one job. The blocks follow the order the decision actually takes: name the task, run through the questions, set up the split, check portability, then verify the numbers.

One thing underpins the whole card. Much of the result comes from the model running underneath, not from the tool itself. Features, prices and limits here reflect May 2026; check both agents' current documentation before you decide.

1. Name the task

Picking a tool "for good" ends in an argument. Picking one for a single task is something you can test.

[ ] Write down in one sentence the task you want to give the agent.
[ ] Decide what the output is: something people look at (a page, an interface, a dashboard), a document (a report, a PDF), or working logic (an automation, a bug fix).
[ ] Note whether the task starts with thinking (a plan, a strategy, a hard problem) or with executing a plan that already exists.
[ ] Note whether the task needs web research.
[ ] List three to five conditions a good result has to meet, before you open either tool.

You match the agent to the task, not to your habits. Name the job and its acceptance conditions first.

2. Task type → agent

These pairings come from the feature comparison and from a test on three identical prompts. Treat them as a starting point, not a verdict.

[ ] Complex front end where the look matters → start with Claude Code.
[ ] The task needs deep planning or brainstorming → Claude Code.
[ ] You want the agent to bring in sub-agents on its own (helpers for planning, searching, reviewing) → Claude Code; Codex only does this when explicitly asked.
[ ] You're building your own workflow from hooks (automatic triggers), skills and messaging channels → Claude Code.
[ ] You're embedding an agent in your own product → Claude Code via the Agent SDK.
[ ] Your company hosts its AI on Amazon Bedrock, Google Vertex AI or Microsoft Foundry → Claude Code.
[ ] The task is web research that ends in a structured report or PDF → start with Codex.
[ ] You want one app from a separate working copy of the project (a worktree) all the way to pushing code → Codex.
[ ] You want the agent to test a finished app by clicking through it and log bugs with steps to reproduce → Codex.
[ ] You work in GitHub pull requests and want to tag the agent in a comment → Codex (@codex).
[ ] The project needs image generation inside the same app → Codex.
[ ] A long task with a stopping condition you can check → both now have /goal.

When a task fits both columns, split it into a thinking part and a doing part, and go to block 4.

3. Questions to ask before you pick

[ ] How much of my session limit is left? Codex wrote two to five times fewer output tokens, and output tokens cost more than input.
[ ] Will the project fit in the context window, the amount of text a model can hold in view at once? In May 2026 Claude Code went up to one million tokens, Codex about 256,000.
[ ] Am I working inside a third-party agent wrapper? OpenAI lets you sign in there with a ChatGPT account; Anthropic doesn't allow it without prior approval.
[ ] Which subscription do I already have? Codex comes with every ChatGPT plan; Claude Code comes with Claude plans from Pro upwards.
[ ] Do I need a partner who pushes back when I'm heading the wrong way, or an executor who sticks to instructions?
[ ] Will a person judge the result by eye (the look), or can it be checked with a test or a comparison?

Speed on a single run is the weakest argument. Limits, context and whether the result can be verified count for more.

4. A recipe for splitting the work

Claude Code behaves more like a thinking partner; Codex sticks to instructions better and is strong at review. That's a qualitative observation, but it gives you a simple recipe.

[ ] Plan with Claude Code: describe the problem, ask it to question you and challenge your assumptions.
[ ] Save the plan to a file in the repository rather than leaving it in the chat window.
[ ] Hand the plan to Codex to execute, step by step.
[ ] Or the other way round: Claude Code builds, and Codex gets the finished code to review for bugs and gaps.
[ ] Review notes go back into the plan file before you start fixing.
[ ] When you're done, ask each agent to read its session log (the JSONL file) and report time and token counts.

Planning and review come from a different agent than execution. A second pair of eyes catches what the first one missed.

5. Portability: a project is a folder

[ ] Check that everything the agent knows about the project lives in files in the repository, not in chat history.
[ ] Note the instructions file: Claude Code reads CLAUDE.md, Codex reads AGENTS.md.
[ ] When switching, open the project in the other agent and ask: this project was built in a different tool, walk through it, understand it, and update whatever needs changing.
[ ] Check that your skills work in the other agent; the format is shared, but tool names inside the instructions may not match.
[ ] Check your MCP servers (connected outside tools); both agents support them, but each is configured separately.
[ ] If you're comparing over a longer stretch, consider keeping two versions of the project, one per agent.

You aren't tied to a tool as long as your project is a folder of files. Keep it that way.

6. Before you trust old numbers

Both tools change every few weeks. The figures below are from May 2026 and are listed so you know what to recheck.

[ ] Plan prices (then: Claude Pro 20 dollars, Max 100 and 200 dollars; ChatGPT Plus 20 dollars, Pro 200 dollars).
[ ] Context windows (then: up to one million tokens in Claude Code, about 256,000 in Codex).
[ ] Number of hook events (then: around 30 in Claude Code, around six in Codex).
[ ] Which features left preview and which were dropped (/ultraplan, /ultrareview, /goal).
[ ] The model versions underneath; the comparison results (GPT-5.5 versus Opus 4.7) will shift with new models.
[ ] The rules on using your subscription inside third-party wrappers.
[ ] Remember the comparison covered three runs, and one of them was a clear outlier.

The difference in philosophy will hold. Check the exact numbers in current documentation, not in notes from last quarter.

After the decision

The cheapest test is one real task from this week, run through both agents and compared against your block 1 conditions and the session logs. The principle I take from this: you don't choose an agent for good, you match it to the task in front of you, and portable files make that choice cost you nothing.