Two agent CLIs, one repo: sharing context between Claude Code and Codex without stepping on each other

I run Claude Code and Codex against the same codebase every day on macOS. For the first month they kept overwriting each other's work, and I spent more time relaying context than writing code.

Key takeaways.

• Two agent CLIs in one repo need one shared instruction file, not two that drift apart.

• Git worktrees give each agent its own checkout, so edits stop colliding.

• A handoff file beats re-explaining context, and the win is minutes per task, not magic.

The problem: two agents, one repo, duplicated context.

I pay for Claude Max and a Codex plan separately. Claude Code is faster at multi-file refactors. Codex is steadier on small, well-scoped edits. So I ran both, on the same repository, at the same time.

Three things went wrong.

Duplicated context. I kept two instruction files: CLAUDE.md for Claude Code and AGENTS.md for Codex. They drifted within a week. I fixed a build command in one and not the other. Both agents then followed stale rules, and I couldn't tell which file had won until a test failed.

Conflicting edits. Same working tree, two processes. Claude refactored a module while Codex edited a test that imported it. One write clobbered the other. git status stopped being readable.

Me as the message bus. Claude produced a plan. I pasted it into Codex. Codex produced a diff. I pasted the summary back. I timed six of those handoffs in one week: 11 minutes each, on average, of pure copy-paste and re-orientation. Roughly 66 minutes a week spent being a clipboard.

What I tried first, and what broke.

• Two instruction files. Keep CLAUDE.md and AGENTS.md in sync by hand. Broke on drift. It turns out Claude Code reads AGENTS.md directly (v2.1.277 and later), so the duplicate was never necessary.

• One terminal, two sessions. Cheapest thing to try, and it failed fastest. Same files, same checkout, collisions within an hour.

• A shared notes file both agents wrote to. The notes file itself became the conflict. Two agents writing prose at each other is worse than two agents writing code at each other.

• Symlinking CLAUDE.md to AGENTS.md. Half-worked. Claude reads through the link, but its Edit and Write tools refuse to write through a symlink, and a symlink committed to git checks out as plain text on Windows.

The pattern is obvious in hindsight: I was fixing the prompt layer and ignoring the filesystem layer.

The setup that works.

One instruction file, read by both.

AGENTS.md at the repo root. Both CLIs read it. It holds facts that belong in every session, nothing else.

# AGENTS.md

## Repo
- TypeScript monorepo. pnpm workspaces. Node 22.
- App code in `apps/`, shared packages in `packages/`.

## Commands
- Install: `pnpm install`
- Test: `pnpm test`
- Lint: `pnpm lint`
- Typecheck: `pnpm typecheck`

## Rules
- Run `pnpm lint` and `pnpm typecheck` before you say a task is done.
- Never edit `pnpm-lock.yaml` by hand.
- Read `.agent/HANDOFF.md` before you touch anything.

## Compact instructions
When compacting, keep test output and code changes.

## Code Review Rules
- Flag any write to `apps/billing/` that skips input validation.

Two hard limits here. Claude Code wants CLAUDE.md files under 200 lines; longer files burn context and get followed less reliably. Codex caps the combined instruction size at project_doc_max_bytes, 32 KiB by default. Both limits punish a file that tries to explain everything. Keep the shared file thin and push detail into path-scoped rules and skills.

A thin CLAUDE.md that just imports it.

Claude Code reads AGENTS.md by default only when there's no CLAUDE.md above the working directory. I want a couple of Claude-specific lines, so I keep a small CLAUDE.md that imports the shared file:

@AGENTS.md

## Claude Code
- Use plan mode for changes under `apps/billing/`.
- Clear context between unrelated tasks.

The import loads first, my additions read last. @AGENTS.md is the portable choice over a symlink; the AGENTS.md spec covers the file itself, and the import is the one thing Codex ignores.

Verify it loaded instead of assuming. In Claude Code, run /context and check the Memory files list. In Codex, the instruction chain rebuilds on every run, so codex --ask-for-approval never "List the instruction sources you loaded" shows the precedence order.

One worktree per agent.

This is the piece that stopped the collisions. Each agent gets its own checkout and branch from the same repository, using plain git worktree:

# main checkout: I review diffs here
git worktree add ../repo-codex -b agent/codex-auth
cd ../repo-codex
codex "Rotate access tokens on refresh. Scope: apps/auth only."

Claude Code stays in the primary checkout; Codex runs in the worktree. They share git history but not files. If I need a third agent, I add a third worktree. Conductor documents the same pattern for parallel Claude Code sessions, and Claude Code has its own worktree guide.

One 2026 detail worth knowing: Claude Code's auto memory directory is keyed by git repository, so all worktrees of the same repo share one memory directory. Good for continuity, bad if you want the two agents to keep separate learnings.

A handoff file, written by the agent that finishes first.

The message-bus problem needed a file, not a transcript. .agent/HANDOFF.md, rewritten at the end of each task:

# .agent/HANDOFF.md
owner: codex
branch: agent/codex-auth
files touched:
- apps/auth/session.ts
- apps/auth/session.test.ts
done: refresh returns rotated tokens
open: a 401 mid-refresh needs a retry cap
next: claude adds the retry cap in apps/api/

The rule in AGENTS.md is one line: read it before you touch anything. Claude picks up where Codex stopped without me pasting a plan. The files touched list also tells each agent where the file-boundary sits, which is the actual collision guard.

What it costs in tokens and time.

Numbers from my own runs, not benchmarks.

• Handoffs. Down from ~11 minutes to well under one. The file is short, so the context cost is a few hundred tokens per read instead of a pasted plan.

• Prompt caching. A typical Claude Code session shows roughly 90% of input tokens served from cache (91% in the docs' own example). Short, stable instruction files keep that prefix cacheable.

• Idle background. Claude Code spends under $0.04 per session on summarization and command checks even when you're not typing.

• The real cost. Agent teams that run in plan mode consume about 7x the tokens of a standard session. Two agents on one feature is not free, and if you split tasks badly you pay roughly double for the same lines of code.

Running locally on your own subscriptions.

Both CLIs authenticate as me, on plans I already pay for. No API key is handed to a third party, no account is shared, no tokens get resold. On Max, the dollar figure Claude Code prints in /usage is an estimate computed at API list price, not a charge; usage draws against the plan's rolling allowance. The whole workflow runs on my laptop, which is why a flaky connection never blocks a task.

What I'd do differently.

• Start with worktrees on day one. I lost the first month to a file-collision problem that a single git worktree add solves.

• Never keep two instruction files. One AGENTS.md, one import, done.

• Split work by file boundary, not by feature. "Codex owns apps/auth, Claude owns apps/api" held. "Codex does the backend, Claude does the frontend" did not, because the boundary moved every hour.

• Write the handoff file by hand for a week before automating it. The fields I thought I needed were not the fields that mattered. What mattered was files touched and next.

What's next.

I want the handoff to be a handoff, not a shared mailbox, so the next step is a small orchestrator: one canvas, each CLI in its own terminal pane, one context file, a visible handoff between panes. That's the tool I ended up building around this workflow - an agent orchestration workspace at starkomand.com that runs each CLI locally on the subscriptions you already have, with no keys or account in the middle.

If you want to try the manual version first, the whole setup is three files and one command:

git worktree add ../repo-codex -b agent/next-task

The instruction file and the handoff file do the rest. I'll write up the orchestrator once it's past the parts that still break, and cross-post it to dev.to under the anthropic tag (the platform caps you at four tags per post). If you've run two agent CLIs on one repo, the thing I'd most like to know is where your file boundary broke.