Claude Code and Codex Working Together: A Practical Handoff Guide
The simplest way to get Claude Code and Codex working together is to share repository instructions and pass work through an explicit handoff file. Codex reads AGENTS.md before starting work. Claude Code can also read it directly on supported versions, or import it through CLAUDE.md. That provides shared guidance, not a shared conversation. (Codex instructions, Claude Code memory)
Start with sequential collaboration: one tool implements a bounded change, then the other reviews the resulting diff against written acceptance criteria. Give each tool the same repository state, constraints, and test evidence. Neither needs the other tool’s private transcript to continue effectively.
1. Establish one shared instruction file
Use a root-level AGENTS.md for stable project rules: verified build commands, testing expectations, dependency policy, and boundaries that apply to every task. Keep temporary progress notes elsewhere.
For example, adapt this template to the actual repository:
# Project working agreements
## Verification
- Use the build and test commands documented in README.md.
- Report the exact commands run and their results.
- Identify checks that could not run and explain why.
## Change boundaries
- Ask before adding production dependencies.
- Do not change public API behavior without approval.
- Keep unrelated formatting changes out of task patches.
## Handoffs
- Read HANDOFF.md when a task explicitly references it.
- Verify the branch and commit before continuing.
- Update the handoff before returning unfinished work.
Codex builds its instruction chain at startup. It checks global guidance, then project files from the project root to the working directory. AGENTS.override.md takes precedence over AGENTS.md within the same directory, and the combined project guidance has a default 32 KiB limit. Restart Codex after changing instructions that must apply to the next task. (Codex instruction discovery)
Make Claude Code load the same rules
Direct AGENTS.md support requires Claude Code v2.1.277 or later. By default, a CLAUDE.md or CLAUDE.local.md in the working directory or above it makes Claude load those files instead of AGENTS.md. A repository can therefore contain both files without both being active. (Claude Code AGENTS.md support)
If the project already uses CLAUDE.md, an explicit import is a straightforward option:
@AGENTS.md
## Claude-specific guidance
- Use plan mode before proposing a billing migration.
Claude documents this import approach for projects with existing Claude instructions and sessions where direct AGENTS.md loading is unavailable. Alternatively, supported sessions can select claude-md-and-agents-md under Project instructions in /config. (Shared instruction setup)
Verify rather than assume. In Claude Code, run /memory and look for the AGENTS.md path, or inspect /context. Before v2.1.280, /memory and /context did not list an AGENTS.md that Claude read directly; on those versions, ask Claude what its project instructions say instead. (Claude Code memory) In Codex, ask it to list active instruction sources and summarize the applicable rules. Remember that Claude does not directly load AGENTS.override.md, so Codex-specific overrides are not automatically shared policy. (Claude loading checks, Codex setup verification)
2. Use a handoff file for changing task state
Shared instructions explain how to work. A handoff explains what happened and what comes next.
Create HANDOFF.md, or a task-specific document, when switching tools. The filename is a workflow convention, not a special command. Explicitly tell the receiving tool to read it.
A useful handoff might look like this illustrative example:
# Handoff: invoice export validation
## Goal
Reject invalid date ranges without changing valid exports.
## Repository state
- Branch: fix/invoice-export-validation
- Commit: <actual commit hash>
- Uncommitted changes: <list or none>
## Decisions
- Preserve the existing response shape.
- Do not add dependencies.
## Completed
- <actual implementation changes>
## Verification
- Command: <exact command>
- Result: <actual result>
- Not checked: <remaining verification>
## Next action
Review the diff for boundary-date errors before editing.
## Open questions
- <unresolved question and decision owner>
Ask the outgoing tool to draft this from the actual diff and command output, then review it. Do not let “tests passed” stand without the command and scope. Distinguish implemented behavior from proposed behavior, and confirmed decisions from guesses.
Use a receiving prompt such as:
Read AGENTS.md and HANDOFF.md. Confirm the current branch, commit, and uncommitted changes. Summarize the goal and unresolved questions. Review the implementation against the acceptance criteria without editing files yet. Flag anything the repository contradicts.
This makes the handoff a checkable starting point rather than an instruction to trust the previous tool blindly.
3. Know when to use /compact, /clear, or a handoff
These solve different problems:
| Mechanism | Purpose | Cross-tool role | | --- | --- | --- | | /compact | Summarizes Claude’s conversation to free context while continuing it | Does not deliver that summary to Codex | | /clear | Starts a new Claude conversation with empty conversational context | Does not create a portable handoff | | Handoff file | Records selected task state for an explicitly identified recipient | Can be read by either tool or another person |
Claude’s /compact [instructions] replaces conversation history with a summary. /clear starts fresh, while the previous saved conversation remains resumable with /resume. Project memory remains available across fresh conversations. (Session context controls, Command reference)
Use /compact when staying on the same task and needing more context space. For example:
/compact Preserve acceptance criteria, unresolved failures, and decisions.
Use /clear when moving to unrelated work. Before either a tool switch or a person-to-person handoff, write the durable task state separately.
Project-root CLAUDE.md is re-read after compaction. Nested instruction files and path-scoped rules reload on demand. Critical requirements left only in chat are therefore a poor substitute for maintained project instructions. (What survives compaction)
4. Start sequentially, then isolate parallel work
A manageable first workflow is:
- Define acceptance criteria and prohibited changes.
- Give one tool implementation ownership.
- Inspect the diff and record verification results.
- Update the handoff with the exact repository state.
- Ask the other tool for a read-only review.
- Assign fixes to one editor, then rerun relevant checks.
Either tool can implement or review. Choose roles based on the task and observed results, not an assumed vendor advantage.
For parallel work, use separate branches and working copies or Git worktrees. Assign non-overlapping tasks and identify who integrates them. Avoid two agents editing the same checkout concurrently: each may reason from files the other is changing.
Isolation does not eliminate integration problems. Two patches can modify different files yet disagree about an interface. After combining changes, rerun the relevant tests against the integrated result, not just each tool’s isolated patch.
Keep approval and permission settings appropriate to each environment. Written project rules are guidance, not a security boundary. Claude explicitly distinguishes instruction files from enforced settings and hooks. (Instruction enforcement limits)
5. Close the cross-tool and cross-person gap
Repository instructions and handoff files cover much of a solo developer’s workflow. They do not automatically preserve the broader project record.
A new contributor may still need to know:
- Which client request defines the current scope.
- Who approved a change in behavior.
- Why an apparently simpler approach was rejected.
- Which release risks remain unresolved.
- Who owns the next decision.
Claude’s auto memory is machine-local, even though worktrees of the same repository share it locally. It is not automatically available on another person’s machine or in another cloud environment. Claude’s local session-resume features restore Claude conversations, not a common Claude-and-Codex workspace. (Auto memory scope, Session storage and resume)
Hark is a shared project record; it does not transfer private chat transcripts. (Hark client handoff: a project record, not a transcript dump) Use that distinction when deciding what to share. The handoff page describes keeping the accepted handoff and accepted decisions in the project record and repository, with a session link only when its detail is useful, rather than treating an entire coding conversation as the deliverable. (Hark client handoff)
For setup details, consult Hark’s Claude Code connection guide. For transferring responsibility beyond the developer’s terminal, see the client handoff use case.
Keep the responsibilities clear: Git records the code, instruction files record working rules, the task handoff records immediate continuation state, and the shared project record preserves context intended for collaborators. Review shared material for secrets and client-sensitive information before publishing it.
FAQs
Can Claude Code and Codex share the same AGENTS.md?
Yes, subject to Claude’s version and loading configuration. Codex reads AGENTS.md natively. Claude can read it directly on supported versions or import it through CLAUDE.md. Verify loading, especially when Claude-specific files or Codex overrides exist. (Claude memory, Codex instructions)
Does /compact send Claude’s context to Codex?
No. It summarizes the current Claude conversation to free context. For a tool switch, create a reviewed handoff file and explicitly ask Codex to read it. (Claude session controls)
Does /clear erase the previous Claude conversation?
It starts a new conversation with empty context, but the previous saved session remains available through /resume. It is a context reset, not a cross-tool transfer or transcript-deletion command. (Claude session management)
Can Claude import Codex configuration instead?
Where /import is available, Claude’s /import codex can bring supported configuration into Claude Code; /import codex --dry-run previews changes. The command reference says /import is not available on Amazon Bedrock, Google Cloud’s Agent Platform, Microsoft Foundry, Claude Platform on AWS, Claude apps gateways, or when feature-flag fetching is turned off. (Import command) Instruction imports are a one-time copy, not ongoing synchronization or shared chat history. Maintain shared rules deliberately afterward. (Import command, Instruction migration)
Sources
