Codex-Claude Handoff
One drives. One challenges. Neither ships alone.
The handoff is only the transport. The product is an accountable engineering
workflow between Codex and Claude Code on the same live Git task. By default,
Codex routes and scopes, Claude Code investigates or implements, Codex reviews
independently, and the user approves sensitive actions.
The agents do not merely pass a summary, run the same prompt in parallel, or let
the Implementer grade its own work. They share durable task state, can challenge
assumptions through scoped questions, and can send a rejected implementation back
for correction. The automated review/correction path is bounded by turn, time, and
budget limits. General question dialogue still advances through explicit turns.
What makes it different
- One accountable task, not two disconnected answers. Both agents work from
the same durable state, scope, decisions, and evidence in the Git project.
- One implements; another challenges. The Reviewer must remain different from
the Implementer and can reject the work instead of merely commenting on it.
- Correction is part of the protocol. A blocked review can return the exact
approved scope for another bounded implementation pass.
- Continuity survives tool boundaries. Project-local files preserve the next
actor and the reasoning needed to resume across VS Code windows and CLI turns.
- Model choice follows the work, not a frozen model list. The Master selects
a stable economy, standard, read-only, or high-reasoning profile. The installed
Claude adapter maps that profile to whatever current Claude model the project
configures and safely inherits the host default when no mapping exists. For
Codex UI turns, the same profile is guidance because the host controls selection.
- Fails closed on inconsistent roles, scope mismatches, no-progress turns,
timeouts, or malformed review output.
- Keeps roles configurable: with explicit user approval, Codex and Claude Code can
exchange Master and Implementer responsibilities.
- Requires the Reviewer to remain different from the Implementer. Automation
availability depends on the verified adapter for the selected role and tool.
- Stops before commit, push, tag, release, deploy, database, or secret actions
until the user provides the protocol's exact authorization.
Run this skill only after explicit user activation.
First use
Check for .ai/skills/codex-claude-handoff/SKILL.md in the project root.
If it is missing:
- Explain that setup copies project-local protocol files and updates
.gitignore.
- Obtain explicit user approval before running setup.
- On Windows, run the bundled
scripts/setup.ps1. Prefer the copy under
.agents/skills/codex-claude-handoff/; fall back to .claude/skills/.
- On macOS/Linux, run the bundled
scripts/setup.sh from the same locations.
- Do not download or execute any additional remote code. The setup payload is
bundled inside this skill.
- Report the doctor result and tell the user which stable files should be
reviewed and committed. Do not commit them automatically.
Installed workflow
When the canonical protocol exists:
- Read
.ai/roles/ROLE_ASSIGNMENT.md and confirm the current role.
- Read
.ai/skills/codex-claude-handoff/SKILL.md for the shared protocol index.
- Read
.ai/skills/codex-claude-handoff/CODEX.md when acting as Codex, or
.ai/skills/codex-claude-handoff/CLAUDE.md when acting as Claude Code.
- Read
AI_HANDOFF.md and continue according to its current state.
The default binding is Codex as Master + Reviewer and Claude Code as Implementer.
Do not change the binding without explicit user approval. After an approved role
swap, keep Reviewer and Implementer different and follow ADAPTERS.md for the
automation supported by the new binding.
Safety
- This is a public beta intended for supervised, human-in-the-loop use.
- Never commit, push, tag, release, deploy, change a database, or change secrets
without the protocol's exact user authorization.
- Keep local coordination and evidence files out of Git.
- If setup, role binding, scope, or state is inconsistent, stop and report the
blocker instead of guessing.
1---2name: codex-claude-handoff-23description: Turn Codex and Claude Code into an accountable engineering pair on one Git task: one agent leads or implements, a different agent challenges and reviews, rejected work can return for bounded correction, and neither ships alone. Durable project-local state preserves scope, decisions, evidence, and the next actor across windows and CLI turns; exact-scope and fail-closed checks stop unsafe or inconsistent progress. Stable capability profiles can resolve to replaceable local model mappings without freezing provider model names, while the user retains approval over sensitive actions. Roles can be swapped with explicit user approval. Use when the user explicitly selects or names codex-claude-handoff, requests cross-agent implementation and independent review, setup, diagnosis, role reassignment, or the full supervised workflow. Do not trigger for ordinary project tasks. On first use, request approval before installing the bundled protocol.4license: Apache-2.05---67# Codex-Claude Handoff89**One drives. One challenges. Neither ships alone.**1011The handoff is only the transport. The product is an accountable engineering12workflow between Codex and Claude Code on the same live Git task. By default,13Codex routes and scopes, Claude Code investigates or implements, Codex reviews14independently, and the user approves sensitive actions.1516The agents do not merely pass a summary, run the same prompt in parallel, or let17the Implementer grade its own work. They share durable task state, can challenge18assumptions through scoped questions, and can send a rejected implementation back19for correction. The automated review/correction path is bounded by turn, time, and20budget limits. General question dialogue still advances through explicit turns.2122## What makes it different2324- **One accountable task, not two disconnected answers.** Both agents work from25 the same durable state, scope, decisions, and evidence in the Git project.26- **One implements; another challenges.** The Reviewer must remain different from27 the Implementer and can reject the work instead of merely commenting on it.28- **Correction is part of the protocol.** A blocked review can return the exact29 approved scope for another bounded implementation pass.30- **Continuity survives tool boundaries.** Project-local files preserve the next31 actor and the reasoning needed to resume across VS Code windows and CLI turns.32- **Model choice follows the work, not a frozen model list.** The Master selects33 a stable economy, standard, read-only, or high-reasoning profile. The installed34 Claude adapter maps that profile to whatever current Claude model the project35 configures and safely inherits the host default when no mapping exists. For36 Codex UI turns, the same profile is guidance because the host controls selection.37- Fails closed on inconsistent roles, scope mismatches, no-progress turns,38 timeouts, or malformed review output.39- Keeps roles configurable: with explicit user approval, Codex and Claude Code can40 exchange Master and Implementer responsibilities.41- Requires the Reviewer to remain different from the Implementer. Automation42 availability depends on the verified adapter for the selected role and tool.43- Stops before commit, push, tag, release, deploy, database, or secret actions44 until the user provides the protocol's exact authorization.4546Run this skill only after explicit user activation.4748## First use4950Check for `.ai/skills/codex-claude-handoff/SKILL.md` in the project root.5152If it is missing:53541. Explain that setup copies project-local protocol files and updates `.gitignore`.552. Obtain explicit user approval before running setup.563. On Windows, run the bundled `scripts/setup.ps1`. Prefer the copy under57 `.agents/skills/codex-claude-handoff/`; fall back to `.claude/skills/`.584. On macOS/Linux, run the bundled `scripts/setup.sh` from the same locations.595. Do not download or execute any additional remote code. The setup payload is60 bundled inside this skill.616. Report the doctor result and tell the user which stable files should be62 reviewed and committed. Do not commit them automatically.6364## Installed workflow6566When the canonical protocol exists:67681. Read `.ai/roles/ROLE_ASSIGNMENT.md` and confirm the current role.692. Read `.ai/skills/codex-claude-handoff/SKILL.md` for the shared protocol index.703. Read `.ai/skills/codex-claude-handoff/CODEX.md` when acting as Codex, or71 `.ai/skills/codex-claude-handoff/CLAUDE.md` when acting as Claude Code.724. Read `AI_HANDOFF.md` and continue according to its current state.7374The default binding is Codex as Master + Reviewer and Claude Code as Implementer.75Do not change the binding without explicit user approval. After an approved role76swap, keep Reviewer and Implementer different and follow `ADAPTERS.md` for the77automation supported by the new binding.7879## Safety8081- This is a public beta intended for supervised, human-in-the-loop use.82- Never commit, push, tag, release, deploy, change a database, or change secrets83 without the protocol's exact user authorization.84- Keep local coordination and evidence files out of Git.85- If setup, role binding, scope, or state is inconsistent, stop and report the86 blocker instead of guessing.
siglernir-ai