How to make Claude Code and Codex hand off tasks to each other

Claude Code and Codex do not send work to each other on their own. To hand off a task you can copy it between two terminals, keep a hand-off file in the repository that both agents read, or have one agent run the other's non-interactive mode (claude -p or codex exec) and read the answer. In MAO, you draw a wire between a Claude Code terminal and a Codex terminal, and each one sends the other tasks with mao ask and gets the result back.

Can Claude Code and Codex talk to each other directly?#

Not out of the box. Neither tool's documentation describes a command that sends a task to the other agent, so something has to carry the task across: you, a file, a shell command or an orchestration app.

Each tool gives you a way in. Both run non-interactively from a shell, both read an AGENTS.md file in the repository, and both can use MCP servers. The sections below show what each of these does for a hand-off, and where it stops.

How do I hand off by copying between terminals?#

Run claude in one terminal and codex in another, in the same repository. Ask Claude Code for a plan, copy it, paste it into Codex, then copy Codex's summary back into Claude Code for review.

It needs no setup and both agents stay fully interactive, so you can steer either one. The cost is you: every hand-off is a copy, a paste and a check that nothing was cut off, and you keep track of which agent is waiting for what. It is fine for an occasional second opinion, and tiring for a loop of plan, build and review.

How do I hand off through a file in the repository?#

Put the hand-off in a file both agents read, so the task and its result live in the repository instead of in your clipboard. Both tools already read AGENTS.md, which makes it the natural place for the shared rules.

• Codex reads AGENTS.md from the project root down to the current directory, at most one file per directory, and stops adding files once they reach 32 KiB combined (the project_doc_max_bytes setting).
• Claude Code (2.1.277 or later) reads AGENTS.md when there is no CLAUDE.md in the working directory or above it. If there is one, add an @AGENTS.md line to CLAUDE.md so Claude Code reads both.

A simple setup:

1. 1In AGENTS.md, write the rule: "Before you start, read HANDOFF.md. When you stop, write what you did, what is left and which files you changed."
2. 2When Claude Code finishes its part, ask it to write the next task into HANDOFF.md.
3. 3Start Codex and tell it to pick up the task in HANDOFF.md.
4. 4When Codex finishes, ask Claude Code to read HANDOFF.md and review the changes.

The file keeps a record you can read and commit, and neither agent depends on your copy and paste. You still tell each agent when to look at it.

Can one agent run the other from its shell?#

Yes. Claude Code's -p flag and Codex's codex exec command each run one task without the interactive interface and print the answer on stdout, so either agent can run the other as an ordinary shell command and read the result.

Claude Code hands a task to Codex

Ask Claude Code to run Codex for the implementation step:

codex exec --sandbox workspace-write "Implement the plan in HANDOFF.md and run the tests" -o codex-result.txt

• codex exec streams its progress to stderr and prints only Codex's final message to stdout, which is what Claude Code reads. -o also writes that message to a file.
• It runs in a read-only sandbox by default. --sandbox workspace-write lets it edit files.
• It expects a Git repository; --skip-git-repo-check turns that check off.
• A follow-up goes to the same Codex session with codex exec resume --last "<prompt>".

To let Claude Code run these commands without asking each time, allow them with a permission rule such as Bash(codex exec *).

Codex hands a task to Claude Code

Ask Codex to run Claude Code for a review:

claude -p "Review the uncommitted changes for bugs and missing tests" --allowedTools "Read,Bash(git diff *)" --output-format json

• claude -p prints the answer and exits. With --output-format json, the text is in the result field and the session_id field lets a later call continue the same conversation with --resume.
• In a -p run, a tool call that needs approval is denied unless something approves it, so list the tools Claude Code may use with --allowedTools or set a mode such as --permission-mode acceptEdits.
• Codex's workspace-write sandbox keeps network access off by default, and claude -p has to reach Anthropic's API. Allow it with network_access = true under [sandbox_workspace_write] in Codex's config.toml.

Script the hand-off yourself

The same commands make a hand-off you run from your own terminal, with each step's output feeding the next:

claude -p "Write a step-by-step plan for adding rate limiting to the API. Output only the plan." > plan.md
codex exec --sandbox workspace-write "Implement plan.md, run the tests and summarize what changed" -o codex-summary.md
claude -p "Read plan.md and codex-summary.md, then review the uncommitted changes against the plan" --allowedTools "Read,Bash(git diff *)"

The trade-off is that the agent you call runs headless, one task per call: you cannot watch it think or step in halfway, and the calling agent waits until it exits.

Does MCP connect Claude Code and Codex?#

Not as a hand-off between two agents. MCP lets one tool use another's tools, which is not the same as handing a task to the other agent.

• Codex using Claude Code. claude mcp serve starts Claude Code as a stdio MCP server, and Codex can add a stdio server with codex mcp add <name> -- <command>. Claude Code's documentation says this server only exposes Claude Code's tools to the client, so Codex gets file, edit and shell tools, not a Claude model taking on the task.
• Claude Code using Codex. OpenAI's documentation says the codex mcp-server command has been removed. Its replacement, the Codex app server, uses its own JSON-RPC protocol rather than MCP and is experimental.

MCP is still useful for giving both agents the same external tools, for example the same documentation or issue-tracker server, added to each with claude mcp add and codex mcp add.

How do wired hand-offs work in MAO?#

MAO runs Claude Code and Codex as real terminals on a canvas, each on its own login and model. A wire between the two lets each one find the other and send it tasks with the mao command, and the result comes back to whichever agent asked.

1. 1Open your repository in MAO and place a Claude Code node and a Codex node.
2. 2Select the Claude Code node, choose Connect on its node bar, and choose the Codex node.
3. 3If Codex will edit code while Claude Code keeps working, put Codex on its own layer. A layer is a git worktree on its own branch, so the two never edit the same checkout.
4. 4Ask Claude Code to plan the change and hand the implementation to Codex. Claude Code sends the task from its own terminal with mao ask, using the name mao peers lists.
5. 5MAO delivers the task into Codex's terminal as soon as it is ready. Codex does the work and finishes the task with mao result <task-id> <content>, and the result is routed back to Claude Code.

Claude Code's side of the hand-off looks like this:

mao peers
mao ask codex "Implement the plan in docs/plan.md, run the tests and reply with what changed"

What the wire gives you:

• Both directions. Two terminals joined by a wire on the same canvas can always send each other tasks, so Codex can ask Claude Code for a review the same way.
• Tracked tasks. Every task has a stable ID and a state: pending, delivered, completed or failed. mao ask waits for the result; mao send returns at once and mao wait <task-id> collects the result later.
• Work that survives a restart. A task that was received but not finished when MAO closed is queued again when MAO starts. After a crash the same task can arrive twice, so recipients should tolerate duplicates.
• Shared context. Wire a note to both agents and each can read it with mao note read <note> and add to it with mao note append <note> <content>.
• Both stay interactive. Each agent is its own live terminal, so you can watch either one and type into it at any point.

Only mao result finishes a task; answering with mao ask sends a new message instead. Prompts and results are limited to 1 MiB each. A wire on one canvas works on every plan, including the free trial; connections to agents on other canvases need a licence.

Which hand-off method should I use?#

Use copy and paste for an occasional second opinion, a hand-off file when you want a written record in the repository, and non-interactive calls for scripted, one-shot steps such as a review in a build script. Use MAO when you hand work back and forth all day and want both agents live, with each task tracked until its result arrives.

What makes a hand-off work?#

A hand-off fails most often because the receiving agent lacks context the sender had. Whichever method you use:

• Say what done looks like. "Tests pass and the endpoint returns 429 after 100 requests" beats "add rate limiting".
• Name the files and the branch. The receiving agent starts with none of the sender's conversation.
• Ask for the result in a fixed shape, such as what changed, what is left and which files were touched, so the sender can act on it.
• Keep shared facts in one file or note instead of repeating them in every message.
• Give each agent its own branch when both edit code at the same time.

Frequently asked questions#

Sources#

• Run Claude Code programmatically: claude -p, piped input, --output-format json, --resume, --allowedTools, permission modes and denied approvals in -p runs.
• Connect Claude Code to tools via MCP: claude mcp add, and claude mcp serve, which only exposes Claude Code's tools to the client.
• How Claude remembers your project: fresh context per session, when Claude Code reads AGENTS.md, and the @AGENTS.md import.
• Codex: Non-interactive mode: codex exec, stdout and stderr, -o, the read-only default, --sandbox workspace-write, --skip-git-repo-check and codex exec resume.
• Codex: Agent approvals & security: network access off by default in workspace-write and the network_access setting.
• Codex: Model Context Protocol: codex mcp add and the [mcp_servers] configuration.
• Codex MCP server removal: codex mcp-server removed, and the app server that replaces it.
• Codex: Custom instructions with AGENTS.md: how Codex finds AGENTS.md and the 32 KiB default limit.
• MAO: Connect agents, notes, and portals: drawing a wire with Connect.
• MAO: Send a task and collect its result: mao ask, mao send, mao result, mao wait, task states and limits.
• MAO: Read and update a connected note: mao note read and mao note append.
• Multi-agent orchestration for coding agents: agents on their own logins, layers as worktrees, results routed to the sender.
• MAO changelog: two-way wires (0.5.24), delivery, restarts and mao result (0.5.25), wires on the free trial (0.11.10).

Checked on 2026-10-28.