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

Neither tool sends work to the other on its own. You can relay text between terminals, keep a hand-off file both agents read, or let one agent run the other's non-interactive mode (claude -p, codex exec). MAO wires the two terminals so they send each other tasks with mao ask and get the results back.

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. In `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. When Claude Code finishes its part, ask it to write the next task into `HANDOFF.md`.
3. Start Codex and tell it to pick up the task in `HANDOFF.md`.
4. When 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. Open your repository in MAO and place a Claude Code node and a Codex node.
2. Select the Claude Code node, choose **Connect** on its node bar, and choose the Codex node.
3. If 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. Ask 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. MAO 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?

| Approach | How the task travels | How the result comes back | Both agents stay interactive | Setup |
| --- | --- | --- | --- | --- |
| Copy and paste | You paste it | You paste it back | Yes | None |
| Shared hand-off file | A file both agents read | Written to the same file | Yes, when told to look | `AGENTS.md` rule and a file |
| Non-interactive call | One agent runs `claude -p` or `codex exec` | On stdout, to the calling agent | No, the called agent runs headless | Permissions and sandbox settings |
| MCP | Not a hand-off: tool calls only | Tool results | Not applicable | `claude mcp serve` and `codex mcp add` |
| MAO wire | `mao ask` or `mao send` over the wire | Routed back to the sender by task ID | Yes | Place two nodes and connect them |

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

### Can Claude Code call Codex?

Yes. From its shell, Claude Code can run `codex exec "<task>"`, which prints Codex's final message on stdout. Codex runs read-only by default, so add `--sandbox workspace-write` when the task needs edits.

### Can Codex call Claude Code?

Yes. Codex can run `claude -p "<task>"` with `--allowedTools` listing what Claude Code may do. Codex's `workspace-write` sandbox turns network access off by default, so allow it with `network_access = true` before the call can reach Anthropic's API.

### Can I use Claude Code as an MCP server for Codex?

You can run `claude mcp serve` and add it to Codex, but it exposes Claude Code's tools, not a Claude agent that takes on a task. To hand over a task, use `claude -p` or a wire in MAO.

### Do Claude Code and Codex share context?

Not automatically. Each Claude Code session begins with a fresh context window and Codex keeps its own sessions, so share what both need through `AGENTS.md`, which both read, or through a note wired to both agents in MAO.

### Do I need API keys for hand-offs in MAO?

No. Each agent runs its own CLI on the login and subscription you already have, and MAO does not route your prompts through its own servers.

## Sources

- [Run Claude Code programmatically](https://code.claude.com/docs/en/headless): `claude -p`, piped input, `--output-format json`, `--resume`, `--allowedTools`, permission modes and denied approvals in `-p` runs.
- [Connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp): `claude mcp add`, and `claude mcp serve`, which only exposes Claude Code's tools to the client.
- [How Claude remembers your project](https://code.claude.com/docs/en/memory): fresh context per session, when Claude Code reads `AGENTS.md`, and the `@AGENTS.md` import.
- [Codex: Non-interactive mode](https://learn.chatgpt.com/docs/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](https://learn.chatgpt.com/docs/agent-approvals-security): network access off by default in `workspace-write` and the `network_access` setting.
- [Codex: Model Context Protocol](https://learn.chatgpt.com/docs/extend/mcp?surface=cli): `codex mcp add` and the `[mcp_servers]` configuration.
- [Codex MCP server removal](https://learn.chatgpt.com/docs/mcp-server): `codex mcp-server` removed, and the app server that replaces it.
- [Codex: Custom instructions with AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md): how Codex finds `AGENTS.md` and the 32 KiB default limit.
- [MAO: Connect agents, notes, and portals](https://trymao.dev/docs/connections-orchestration-mao-cli/node-connections): drawing a wire with **Connect**.
- [MAO: Send a task and collect its result](https://trymao.dev/docs/connections-orchestration-mao-cli/task-delivery): `mao ask`, `mao send`, `mao result`, `mao wait`, task states and limits.
- [MAO: Read and update a connected note](https://trymao.dev/docs/connections-orchestration-mao-cli/bridge-note-access): `mao note read` and `mao note append`.
- [Multi-agent orchestration for coding agents](https://trymao.dev/multi-agent-orchestration): agents on their own logins, layers as worktrees, results routed to the sender.
- [MAO changelog](https://trymao.dev/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.

Source: https://trymao.dev/claude-code-codex-handoff