codex-implement

name	codex-implement
description	Delegate implementation of an approved plan to OpenAI Codex via `codex exec`, the Codex TUI, or a final-only MCP call, then summarize the resulting diff. Use after planning in Claude Code, to offload heavy implementation to Codex and conserve Claude's budget.

codex-implement

Hand implementation work to Codex while Claude Code stays the planner/orchestrator. See docs/claude-codex.md for the full workflow.

When to use

• A plan is ready (Plan mode output, a plan file, or $ARGUMENTS) and the change should be implemented by Codex.
• You want to spend Codex's budget on implementation instead of Claude's.

Steps

1. Check that Codex is available:

   command -v codex
   

   If not found, stop and report: "Codex is not installed on this machine. Install via nix (just build <host>) or run /antigravity-implement as an alternative."

2. Identify the task source, in this order: $ARGUMENTS → the approved plan file → the newest .tmp/plan*.md. If none exists, ask the user what to implement.

3. Make sure .tmp/progress.md reflects the current Goal/Plan (run the handoff skill first if it is stale).

4. Choose the delegation lane:

   Lane A — Autonomous (background): Use when the full plan content can be embedded directly in the prompt and no interactive approval is needed. Read the plan file with Claude's Read tool first, then pass its content inline so Codex never needs to call MCP Read itself — that call fails in a no-TTY background process.

   codex exec -p shared -c approval_policy=never --json -o .tmp/codex-implement.jsonl \
     "<full plan content here>. Follow the standards in ~/.codex/AGENTS.md. Keep changes focused; do not commit."
   

   Run with run_in_background. Use codex exec resume --last to inspect a finished run.

   Lane B — Supervised TUI: Use when the task is complex, approval is needed, or Lane A keeps failing.

   If $HERDR_ENV=1 and command -v herdr succeeds, use the herdr-assisted supervised lane. Use $HERDR_PANE_ID as Claude's own pane id; do not search herdr pane list for the current Claude pane. Split a right-hand pane with herdr pane split "$HERDR_PANE_ID" --direction right --no-focus, then start Codex in the repo with herdr pane run "$CODEX_PANE" "cd <repo> && codex -p shared -a on-request".

   Poll herdr pane list for the Codex pane's agent_status. Do not treat a herdr wait agent-status timeout as proof that Codex is still running; status must be re-read from pane list. Wait for initial idle, then send the plan content directly with pane run (Lane A style — do not send /resume; on codex 0.142.3 it collides with Codex's built-in session-resume picker instead of running the custom prompt).

   Use a polling helper that returns when the Codex pane becomes blocked or idle. If it becomes blocked, end that Bash invocation immediately, show the exact herdr pane read output to the human, and wait for the user's real answer. Do not choose or send an approval automatically. After the user answers, send the selected key/text with herdr pane send-keys or herdr pane send-text, then resume polling.

   When the Codex pane becomes idle, it is done — do not send /handoff (on codex 0.142.3 it is unrecognized, not the custom prompt). Instead run git diff/git status yourself and update .tmp/progress.md with the handoff skill, then close the pane with herdr pane close. Keep the detailed command sequence in docs/claude-codex.md as the source of truth.

   If herdr is unavailable, present this exact block to the user as copy-paste for a separate terminal pane:

   別ペインで以下を実行してください:
   
   codex -p shared -a on-request
   

   Do not instruct the user to send /resume or /handoff. On the Codex CLI versions verified so far, /resume is captured by Codex's built-in session picker (it never reads .tmp/progress.md) and /handoff comes back as "Unrecognized command". See the "既知の別問題" note in docs/claude-codex.md.

   Instead: paste the plan directly into the Codex pane, and when Codex goes idle, inspect git diff / git status yourself and update .tmp/progress.md via the handoff skill.

   Lane C — Final-only MCP: Use only for short, self-contained tasks where no progress stream is needed. Use the MCP codex tool with approval-policy: never.

5. When Codex finishes, run git diff (and git status) and summarize what changed, file by file.

6. Update .tmp/progress.md (Done/Next/Open). Flag anything that needs review with codex-review or Claude's /code-review.

Notes

• Lane A failure mode: codex exec in background spawns claude mcp serve as a subprocess. Without a TTY, MCP tool calls (Read, Bash, Edit) are auto-cancelled with "user cancelled MCP tool call". Fix: embed all needed content in the prompt; do not ask Codex to read files via MCP.
• MCP codex human approval is currently unusable because Codex issue #18268 makes compliant approval responses fall back to Denied. Use TUI (Lane B) for human approval.
• Orchestrating Codex from Claude still consumes Claude tokens. If Claude is near its limit, do not use this skill; tell the user to run codex -p shared directly and /resume from .tmp/progress.md.
• Codex edits files itself; do not also edit them from Claude in parallel.