codex-handoff

Claude Code Codex Handoff

简体中文说明

A Claude Code plugin for repo-grounded handoff to Codex.

Instead of sending a rough coding idea straight to Codex, this plugin lets Claude inspect the repository first, identify relevant files and constraints, and produce a structured implementation brief for Codex to execute.

Why this exists

Direct implementation prompts often miss repository-specific context:

• architecture boundaries
• local conventions
• nearby call paths
• implicit constraints
• test expectations
• review hotspots

This plugin makes that explicit.

Role split:

• Claude: planner, tech lead, reviewer
• Codex: implementer

Workflow:

You -> Claude analyzes repo -> Claude writes CODEX_HANDOFF -> Codex implements -> Claude reviews

When the Codex plugin is installed, the entire pipeline runs automatically with a single command. No manual copy-paste needed.

How context flows

Claude and Codex run as independent processes. They share the working directory (the same git repository) but not conversation history, file read cache, or internal reasoning.

When the handoff skill invokes /codex:rescue, Codex receives only:

1. The text of the # CODEX_HANDOFF section (passed as the args string)
2. Access to the same filesystem (it reads files on its own)

This means the quality of the handoff brief is the primary lever for reducing Codex's exploration cost. The more precise the file paths, scope boundaries, and acceptance criteria, the less Codex needs to re-discover on its own.

The .codex-handoff/ directory is used for Claude-side state passing only:

• .codex-handoff/latest.md — the review skill reads this to cross-reference acceptance criteria and constraints when evaluating Codex's implementation
• .codex-handoff/history/ — timestamped copies of handoff and review outputs for traceability

Codex does not read from .codex-handoff/.

What you get

• codex-handoff:repo-analyst A read-only subagent for repository inspection, architecture mapping, constraints, and test planning.
• /codex-handoff:handoff [--no-exec] [--background] [--model <model>] [--effort <level>] [task] Generates a repo-grounded CODEX_HANDOFF brief, then automatically hands it to Codex for implementation and triggers a review when done. Use --no-exec to only generate the handoff without invoking Codex.
• /codex-handoff:review [--timeout <sec>] [--skip-tests] [scope] A manual review skill for checking the current implementation against intent, risks, and missing tests. Runs the project's test suite (detected from the handoff or from repo shape) and grounds the verdict in the result — failing tests force REWORK. Outputs one of APPROVE, MINOR_FIX, or REWORK alongside a Test results section with the command, exit code, and log path.
• scripts/validate.sh Structural validation plus optional Claude CLI checks.
• scripts/validate.ps1 PowerShell equivalent for Windows environments.

Installation

Option A: Install from plugin marketplace (recommended)

1. Add the marketplace:

   /plugin marketplace add Eilen6316/claude-code-codex-handoff
   

2. Install the plugin:

   /plugin install codex-handoff@codex-handoff
   

3. Reload plugins:

   /reload-plugins
   

Option B: Load locally with --plugin-dir

1. Clone the repository:

   git clone https://github.com/Eilen6316/claude-code-codex-handoff.git
   cd claude-code-codex-handoff
   

2. Load the plugin for the current session:

   claude --plugin-dir .
   

60-second quickstart

1. Install the Codex plugin (required for automatic execution):

   /plugin marketplace add openai/codex-plugin-cc
   /plugin install codex@openai-codex
   /reload-plugins
   /codex:setup
   

2. Run a single command — Claude analyzes, Codex implements, Claude reviews:

   /codex-handoff:handoff add retry protection to the login flow without regressing existing auth state handling
   

   This will automatically:

   • Generate the structured CODEX_HANDOFF brief
   • Pass it to Codex via /codex:rescue for implementation
   • Trigger /codex-handoff:review to review the result

3. To only generate the handoff without executing:

   /codex-handoff:handoff --no-exec add retry protection to the login flow
   

Example

User request:

Add retry with exponential backoff to the token refresh flow used by authenticated API requests.
Reuse any existing retry helper if available.
Do not change public API behavior.
Add or update tests.

Claude analyzes the repository and produces a structured brief.

Representative CODEX_HANDOFF: