Codex CLI next to Claude Code: one rulebook, two agents

TL;DR: I run two coding agents on the same repositories: Claude Code as the default and OpenAI's Codex CLI for bounded jobs that come with a written spec. Both read one rulebook (the Codex instruction file is a symlink to the Claude one), both pass every shell command through the same pre-execution hook, and both see the same MCP servers and the same skills directory, so switching agents never means switching rules. Claude Code keeps planning, incidents, customer-facing text and long threads, because its session can grow to a 1M-token context window. Codex gets spec'd work in its own git worktree, plus second-opinion code review. The only routing question I ask is "do I have a spec yet?"

Why run a second coding agent at all?

The concrete problem was throughput. One agent session is one queue. While Claude Code is deep in a planning thread or an incident, the mechanical work piles up behind it: a list of test cases to write, a bulk rename, a refactor that is already fully planned. On top of that, subscription limits are per product, so a second CLI is a second budget, and a different model family catches different mistakes in review.

I weighed three setups:

• Stay with one agent and run more sessions in parallel. Simple, one set of rules, and it works well with worktrees, as I described in running agents in parallel with git worktrees. The downside is that every session drains the same limit and shares the same blind spots.
• Add Codex, but isolated. No MCP servers, no network, no secrets. Safe by construction, but it can only do half of any real task, and every job needs a hand-over of whatever it could not reach.
• Add Codex with full parity. The same tool access, network, skills, project memory and guardrails as Claude Code. More setup, and more surface to keep in sync.

My first version was the isolated one. I reversed it the same day. The isolation was protecting against things the shared guardrails already block, and it turned a useful second agent into a toy. The split of work between the two stayed, but as a recommendation about what pays off, with no technical wall behind it.

One rulebook: instructions, hooks, MCP and skills

The idea behind parity is that there is exactly one source of truth for each kind of rule, and each CLI gets pointed at it in whatever way it understands. This is context engineering: deciding what an agent sees at the start of a session and where that content lives, so it stays small, current and identical across tools.

Instructions. Claude Code reads CLAUDE.md, Codex reads AGENTS.md. In every repo and at the global level, AGENTS.md is a symlink to the CLAUDE.md next to it. I edit one file and both agents read the change on their next start. There is no second copy to drift.

One hook contract for both CLIs. A hook is a script the agent harness (the CLI wrapped around the model that runs tools, manages context and enforces permissions) calls at a fixed point, here before any shell command runs. Both CLIs hand the hook the pending command as JSON on stdin and treat exit code 2 as "block this, and show the model why". Because the contract is identical, a single script guards both agents against the irreversible categories: history rewrites, force pushes, destructive deletes, dropping remote data.

// illustrative shape only
stdin  -> { "tool_input": { "command": "<the shell command>" } }
exit 0 -> allow
exit 2 -> block; stderr becomes the reason the model sees

Codex also has its own prefix-based command rules, which I keep as a mirror of the Claude Code deny list. They are the weaker layer: prefix matching cannot see a dangerous flag placed later in the command, so the hook stays the primary guard. Codex asks you to trust a new hook once in its UI before it runs it, which is a step you cannot automate away.

MCP parity. MCP, the Model Context Protocol, is the standard way to plug external tools into an agent: log search, database queries, analytics, a browser. Each repo has a small Codex config that mirrors the Claude Code MCP config. The always-on servers are enabled, the heavy ones are listed but disabled, and the launcher (below) turns them on per task. The server names come from the same files Claude Code uses, so there is one list of names. OAuth logins are per CLI and have to be done once by hand in a browser.

Skills and memory. Skills live in one store on disk. Codex scans that store natively; Claude Code gets a per-repo selection through symlinks. One catch: Codex shows the whole store, and its skill catalogue has a budget of roughly 2% of the context, around 8,000 characters, after which descriptions get cut. Project memory is simpler: the launcher tells Codex to read the project's memory index at the start of each session.

Profile launchers: one command picks model, effort and tools

Parity would be tedious if every session needed five flags. So both CLIs start through one small shell script, installed under two names. The name decides the backend. A per-repo profile file decides everything else: each line is a type of work with its keywords, its MCP servers, its Claude model, its effort, a one-line hint for the agent, and its Codex model. A simplified example:

I can name a profile, or type a sentence and let keyword matching pick one, with the everyday coding profile as the fallback. For Codex the launcher does three more things. It can create a dedicated git worktree on its own branch from the current HEAD and install dependencies there (918 packages in 14 seconds from the local cache). It can run Codex non-interactively with a spec read from a file. And it appends a short closing instruction to every task: nobody will answer questions, an unclear spec means stop and report, and the final message lists files, test results and the commit.

Two things broke on the first run. The non-interactive mode reads stdin when there is no terminal and sat for a full minute waiting on an open pipe, so the launcher now closes stdin and passes long specs through a file. And the first commit inside the worktree failed, because a worktree keeps its git metadata in the main repository, which sat outside the sandbox. Codex reported that in its summary instead of trying to get around the sandbox, which is the behavior I want. The fix was to grant write access to that one directory explicitly.

Which agent gets which job?

When I start a session without naming a profile, it always lands in Claude Code. The launcher picks a profile from my words, but it never picks the backend, because the one question that separates the two agents is whether a spec exists, and only a session can answer that. When a Claude session reaches mechanical work that is fully specified, its hint tells it to write the spec to a file and print a ready command for a second terminal. I copy one line.

One early mistake is worth naming. Before any of this existed, I pointed Codex at leads, email and search analytics with no rules at all, and the results were poor. That was a missing-rules problem. Once both agents read the same instructions, the difference between them shrank to model quality and ergonomics.

Model tiers per job, as of September 2026

On the Claude side, Fable 5.1 is the default for planning, incidents, customer text, hard debugging and day-to-day code. Opus 5 runs the sessions that load heavy analytics MCP servers: they pull in thousands of lines of JSON, the analysis does not need the top model, and its API list price is half of Fable's. Sonnet 5, at a fifth of Fable's price, handles quick fixes and mechanical profiles. Haiku 4.5 sits in no profile; its only good use for me is as the model behind many parallel search subagents.

On the Codex side, GPT-5.6 comes in three tiers: Sol as the workhorse, Terra in the middle, Luna as the fast and cheap one. Two details mattered in practice. Sol's default reasoning effort is low, which gives shallow answers, so my profiles set it to high. And in my judgment Sol is slightly weaker than Fable, so it gets tasks with a full spec and never the discovery of what the problem is.

The rules I route by: lower the effort before you lower the model; pick the model by who reads the output (a customer gets the top model, I get the mid tier, a machine gets the fast tier); and change the model at session start, never mid-thread, because the prompt cache is per model and the whole context gets read again. More on why effort matters less than people expect in choosing model and effort in Claude Code.

How big is the context window in Codex CLI compared to Claude Code?

This surprised me. The GPT-5.6 models support around 1.05M tokens through the API, but Codex CLI sets a 272K window and compacts at 95% of it, around 258K. That is a CLI policy: OpenAI bills prompts above 272K input tokens at a higher rate (2x on input, 1.5x on output as of September 2026), so the CLI keeps sessions under that line by default. You can raise the window in config, and I chose not to: above that line the subscription limit burns twice as fast, and when I measured my own Claude Code usage, 88% of tokens went into turns with more than 300K of context already loaded.

Claude Code lets a session grow to 1M with no pricing step on the way. That is the practical reason long threads stay there. I still brake them with a hook that asks the agent to write the state of the thread into the repo docs at 250K, hand off at 400K and 550K, and stop at 650K. The same hook runs in Codex, reading token counts from its session log, with checkpoints at 120K, 200K and 245K, re-armed after each compaction. Codex never reaches the higher thresholds because it trims history first.

What Codex still lacks, and what I would tell you to do tomorrow

Parity has holes. Codex has no equivalent of Claude Code's agent definition files (named subagents with their own model and instructions), and none for artifacts. It also cannot deny reads of specific files: Claude Code has a rule that blocks reading the local secrets file, and Codex has nothing that filters file reads. My workaround is structural. The worktree Codex works in never contains the app's local secrets, because that file is ignored by git, and database or analytics access goes through MCP servers exactly as it does for Claude.

Review is the other cost. Checking a delegated branch takes me about two minutes, whatever its size: the diff, tests green in the main checkout, no stray co-author trailer, scope equal to the spec. That fixed cost means Codex only pays off on tasks worth several minutes of work. The real gain is parallelism and a clean main session. Token savings are a minor part of it.

If I were setting this up from scratch tomorrow:

• Symlink the instruction files on day one. Two rulebooks drift within a week.
• Write guardrails against the shared hook contract. One script, tested once, guards both agents.
• Keep one list of MCP server names and generate or mirror the second config from it.
• Route by "is there a spec?" rather than by which model feels smarter today.
• Run the second agent in its own worktree. Two agents in one checkout will edit the same files.
• Check the default effort of every model you add. A workhorse model on its lowest effort looks worse than it is.

For a comparison with a very different environment, where the agent is chosen for you, see Claude Code at home, Kiro CLI at work.