--- title: "How to run Codex and Claude Code side by side on one project · Cork" description: "Run OpenAI Codex CLI and Claude Code on one repo: one AGENTS.md for both, a worktree each, shared MCP servers, matching hooks, and live coordination." canonical: "https://corkcli.com/blog/run-codex-and-claude-code-side-by-side" last_updated: "2026-10-03" published: "2026-10-03" author: "Kevin Vera" --- # How to run Codex and Claude Code side by side on one project Run OpenAI Codex CLI and Claude Code on one repo: one AGENTS.md for both, a worktree each, shared MCP servers, matching hooks, and live coordination. By Kevin Vera · October 3, 2026 · [Guides](https://corkcli.com/blog/c/guides) · 5 min read To run Codex and Claude Code side by side on one project, keep a single `AGENTS.md` that both agents read, start each agent in its own git worktree on its own branch, register the same MCP servers in both (`claude mcp add` and `codex mcp add`), and attach the same check script to both tools' hooks. That setup prevents most overwrites. It does not tell either agent what the other changed a minute ago, which is where a [coordination layer](https://corkcli.com/blog/coordination-layer-ai-coding-agents) comes in. ## Why run both Teams run Codex and Claude Code together for practical reasons: different models are better at different tasks, a second agent can review the first one's work, or different people on the team simply prefer different tools. The risk is the same as with any two agents on one repo: each has its own context window, neither sees the other's conversation, and both will happily rewrite a file the other is in the middle of changing. ## Step 1: one instruction file for both agents Codex reads `AGENTS.md` natively. As of October 2026, OpenAI's docs describe the discovery order: Codex first checks its home directory (`~/.codex`) for `AGENTS.override.md` then `AGENTS.md`, then walks from the git root down to the current directory, checking each level for `AGENTS.override.md`, then `AGENTS.md`, then any configured fallback names. Files closer to your directory take priority, and the combined size is capped at 32 KiB by default (`project_doc_max_bytes` changes it). Running `/init` in Codex generates an `AGENTS.md` scaffold. Claude Code also reads `AGENTS.md` when there is no `CLAUDE.md` in the working directory or above it (Claude Code v2.1.277 or later). If you keep a `CLAUDE.md` for Claude-specific notes, start it with an import so both agents share one source of truth: ```markdown @AGENTS.md ## Claude Code only - Prefer the Edit tool over sed for multi-line changes. ``` Put the shared contract in `AGENTS.md`: build and test commands, conventions, and who owns which directories while both agents run. ## Step 2: give each agent its own worktree ```bash git worktree add ../shop-codex -b codex/checkout-retry git worktree add ../shop-claude -b claude/invoice-pdf ``` Start `codex` in `../shop-codex` and `claude` in `../shop-claude`. Claude Code can create its own worktree too: `claude --worktree invoice-pdf` puts it under `.claude/worktrees/invoice-pdf/` on a branch named `worktree-invoice-pdf`. Separate worktrees mean neither agent can overwrite the other's files mid-task. They do not prevent semantic conflicts: if Codex changes `charge(amount)` to `charge(amount, currency)` on its branch while Claude Code adds three new calls to `charge(amount)` on another, both branches pass their own tests and the merged result does not compile. ## Step 3: register the same MCP servers in both Claude Code: ```bash claude mcp add --transport http --scope project tracker https://mcp.example.com/mcp ``` The `project` scope writes `.mcp.json` at the repo root, which you can commit. Codex: ```bash codex mcp add tracker --url https://mcp.example.com/mcp codex mcp login tracker # only if the server uses OAuth ``` Or put it in `~/.codex/config.toml` (or a project-scoped `.codex/config.toml`): ```toml [mcp_servers.tracker] url = "https://mcp.example.com/mcp" bearer_token_env_var = "TRACKER_TOKEN" ``` Run `/mcp` in either tool to confirm the server is connected. ## Step 4: run the same checks after every edit Both tools support lifecycle hooks with the same event names for the basics. Claude Code reads hooks from `.claude/settings.json`; Codex reads them from `~/.codex/hooks.json`, `/.codex/hooks.json`, or a `[hooks]` table in `config.toml`, and OpenAI's docs say hooks are enabled by default. Both support `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse` and `Stop`, and both let a `PreToolUse` hook deny a tool call with `permissionDecision: "deny"` or exit code 2. A minimal `PreToolUse` entry has the same shape in both tools: ```json { "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "./scripts/check-command.sh" } ] } ] } } ``` Point both tools at the same script and both agents are held to the same rules. ## Step 5: land one branch at a time When both agents finish, merge one branch, rebase the other onto it, and rerun the tests before merging the second. Do not merge both at once and hope. If the second rebase conflicts, give the conflict back to the agent that owns that branch with the other agent's diff in the prompt. ## How Cork helps Steps 1 to 5 keep two agents apart. They do not let them work on related code at the same time, because neither knows what the other is doing. Cork is the coordination layer for [multiplayer coding agents](https://corkcli.com/blog/multiplayer-coding-agents): it keeps Claude Code, Codex and Cursor agents, on one machine or across a team's machines, from overwriting each other on one codebase, and hands each agent what the others already learned. For Codex plus Claude Code: - **Live awareness**: when Codex changes a signature that Claude Code's work depends on, Claude Code hears about it on its next step, and the reverse. - **[Write gate](https://corkcli.com/blog/write-gate)**: an edit against code the other agent is changing right now is held until your agent has their version. - **[Semantic lint](https://corkcli.com/blog/semantic-lint)**: the rename or new signature becomes a lint rule both agents are checked against, which catches the `charge(amount)` case above before merge. - **Landing**: `git push` becomes one step that rebases onto teammates' commits, reruns the tests, and pushes. Cork's hooks in Claude Code, Codex and Cursor do this with no extra model calls, and its MCP server (`https://mcp.corkcli.com`) works with any MCP client. Install it once per machine: ```bash curl -fsSL https://corkcli.com/install.sh | sh ``` ## Frequently asked questions ### Can Codex and Claude Code edit the same repository at once? Yes, but in a shared checkout they can overwrite each other's files. Give each its own worktree, or use a coordination layer that holds conflicting edits. ### Does Claude Code read AGENTS.md like Codex does? Yes, since v2.1.277 Claude Code reads `AGENTS.md` when no `CLAUDE.md` is present. With a `CLAUDE.md`, add `@AGENTS.md` at the top to import it. ### Can I use the same hooks for Codex and Claude Code? The configuration shape and core event names match, so one script can serve both. Check each tool's input fields before relying on tool-specific values. ### How do I stop Codex and Claude Code from breaking each other's code at merge time? Merge one branch at a time, rebase the other and rerun tests, or use a tool that turns one agent's renames and signature changes into checks for the other. ## Sources - - - - - - - - - ## Related reading - [How to coordinate Cursor and Claude Code on the same codebase](https://corkcli.com/blog/coordinate-cursor-and-claude-code-same-codebase): Run Cursor and Claude Code on one repo without clobbered edits: shared AGENTS.md instructions, worktrees, shared MCP servers, hooks, and a coordination layer. - [How to share context between Codex and Claude Code](https://corkcli.com/blog/share-context-codex-claude-code): Make Codex and Claude Code work from the same context: one AGENTS.md, shared MCP servers, handoff files, and live awareness when both edit the same repo. - [MCP servers for coordinating coding agents: what they are and how to use one](https://corkcli.com/blog/mcp-servers-coordinating-coding-agents): What an MCP server for coordinating coding agents does, how it differs from hooks, and how to connect one to Claude Code, Codex, Cursor and Gemini CLI. - [How to add a remote MCP server to Claude Code, Codex, Cursor and Gemini CLI](https://corkcli.com/blog/add-remote-mcp-server-claude-code-codex-cursor-gemini-cli): Exact, verified commands and config to add a remote HTTP MCP server to Claude Code, Codex, Cursor and Gemini CLI, with scopes, auth headers and OAuth sign-in. [All articles](https://corkcli.com/blog.md) · [Cork in Markdown](https://corkcli.com/index.md) · [llms.txt](https://corkcli.com/llms.txt) This page in HTML: https://corkcli.com/blog/run-codex-and-claude-code-side-by-side