SuperAPI AI Directory

collaborate-with-codex

Coding & development

View repository

Updated 10-24 16:17

About this skill

Collaborate with Codex

Use Claude as the orchestrator and final acceptance owner. Prefer Codex as the bounded implementer and test runner, followed by Claude's independent review. Keep one writer per worktree and reuse the same Codex thread for revisions.

If this skill was explicitly invoked, treat the following as additional task direction:

$ARGUMENTS

Decide whether to delegate

Use Codex when at least one condition holds:

  • The user explicitly asks for Codex or cross-model collaboration.
  • The change is complex, high-risk, or spans several files or subsystems.
  • The task involves a difficult bug, migration, refactor, security review, performance work, or unfamiliar code.
  • An independent implementation, diagnosis, or second opinion can materially reduce risk.
  • The task has objective acceptance criteria and Codex can run meaningful verification.

Do not delegate merely to duplicate work. Handle explanations, trivial edits, formatting, obvious one-file fixes, and low-risk mechanical changes directly unless the user asks otherwise.

Verify availability

Use the MCP tools provided by the server named codex:

  • mcp__codex__codex starts a Codex task and returns a threadId.
  • mcp__codex__codex-reply continues that task using the returned threadId.

If these tools are deferred, discover them with tool search. If they are unavailable, check the MCP connection without changing its configuration. Tell the user exactly what is unavailable instead of pretending Codex participated. Do not silently replace MCP collaboration with a shell invocation of Codex.

Assign roles

Default to this asymmetric workflow:

  1. Claude clarifies the request, identifies constraints, and defines acceptance criteria.
  2. Codex implements the bounded change and runs relevant checks.
  3. Claude independently inspects the actual diff and test evidence.
  4. Codex fixes concrete findings in the same thread.
  5. Claude performs final acceptance and reports remaining risks.

Adjust roles when useful:

  • For brainstorming, product behavior, or UX, let Claude lead the specification and ask Codex for technical feasibility or implementation.
  • For diagnosis, Claude and Codex may investigate independently in read-only mode; compare evidence before choosing a fix.
  • For a review-only request, ask Codex for a read-only independent review and treat its output as advisory evidence.
  • Never let a reviewer rewrite working code without a specific defect, requirement gap, or measurable improvement.

Establish a baseline

Before delegating, record enough state to tell later what Codex actually changed. Codex's own summary is not evidence.

  • In a git repository: capture git status --short and the current HEAD, and note any pre-existing uncommitted changes so they are not later mistaken for Codex's work.
  • Outside a git repository: capture a file listing with sizes and mtimes for the in-scope directories, for example ls -lR or find <dir> -type f -newermt '-1 day'.
  • Either way, run the validation command once first when it is cheap. A failure that already exists before delegation is not a regression.

Prepare the task packet

Inspect enough of the repository to send Codex a self-contained task packet. Include:

  • Objective and user-visible outcome.
  • Acceptance criteria.
  • Absolute project working directory.
  • In-scope and out-of-scope files or behavior.
  • Relevant repository instructions and architectural constraints.
  • Known symptoms, reproduction steps, logs, or failed tests.
  • Required validation commands.
  • Forbidden actions such as committing, pushing, publishing, deleting data, changing dependencies, or broad rewrites.
  • Expected return: changed files, validation results, unresolved risks, and a concise summary.

For any delegation expected to run longer than a few minutes, also require a progress trail: instruct Codex to append one line to PROGRESS.md in the working directory as it finishes each milestone, stating what it completed and what it is starting next. This is the human-readable feed the user can follow while the call blocks.

Do not send vague prompts such as "fix this repo" or ask Codex to rediscover facts Claude already has. Do not expose secrets, credentials, or unnecessary private data.

Size the delegation

A Codex MCP call is synchronous. Claude cannot act, report, or answer the user until it returns, so the size of one call is the size of the blind window.

Aim for a single call that completes within roughly ten minutes. When the work is larger, split it into milestones with their own acceptance criteria and chain them with mcp__codex__codex-reply on the same thread:

  • Each milestone should leave the workspace in a coherent, verifiable state.
  • Prefer boundaries that produce checkable evidence, such as "rename and make the existing suite pass" before "restructure the modules".
  • Between milestones, report progress to the user and re-verify before authorizing the next one. This is also the user's opportunity to redirect or stop.

Do not split work that is genuinely atomic just to hit the time target, and do not pad the thread with milestones that produce no verifiable state.

Isolate Codex in a worktree

Prefer giving Codex its own git worktree whenever the repository holds work the user cares about. Create it from the main session before delegating:

git worktree add -b codex/<slug> <absolute-worktree-path> <base-ref>

Pass that absolute path as Codex's cwd. Containment comes from that cwd plus the workspace-write sandbox, and from nothing else. In particular, the Agent tool's isolation: "worktree" does not contain Codex: it isolates a subagent's own file edits, while Codex runs as a separate process that writes wherever its cwd points. Never treat agent isolation as a substitute for passing the worktree path.

With the worktree in place:

  • The user's working tree stays untouched while Codex runs, so "one writer per worktree" becomes a physical fact rather than a rule to remember.
  • Review is a clean git -C <worktree> diff for uncommitted work, or git diff <base-ref>...codex/<slug> once anything is committed.
  • Claude lands the work itself after acceptance passes. See "Land the change".

Skip the worktree when the directory is not a git repository, when the task depends on the user's uncommitted state, or when the change is small enough that a direct in-place call is easier to verify than to isolate. Say which case applies instead of silently choosing.

Delegate through a background subagent

For any delegation expected to run longer than a few minutes, put the blocking Codex call inside a background subagent instead of calling it from the main loop. The main session stays responsive: the user can ask questions, redirect, or stop, and Claude can read the rollout log to answer "where is it now".

Spawn a general-purpose agent with run_in_background: true, and make it a courier, not a second implementer. Its prompt must:

  • Forbid it from implementing, editing, or running the validation itself. Its only job is to relay the task packet and report what happened.
  • Tell it to load the Codex tools with ToolSearch (select:mcp__codex__codex,mcp__codex__codex-reply), and to report the failure rather than falling back to a shell codex invocation or doing the work itself.
  • Contain the full task packet verbatim, including the worktree path as cwd.
  • Require it to return: the threadId exactly as returned, Codex's final message verbatim, and the post-run git status --short and git diff --stat for the worktree.

Treat everything the courier returns as Codex's claims relayed one step further, not as verification. Claude still performs the review in the actual worktree.

Correction rounds do not go back through the subagent. Once Claude has the threadId, call mcp__codex__codex-reply directly from the main session — the thread keeps its full context across that boundary.

Tell the user before delegating

A direct Codex call blocks the session outright; a courier subagent does not, but the user still cannot see what Codex is doing. Either way, brief the user in the same turn that starts the work, before the tool call. State:

  • What is being delegated, and the acceptance criteria Codex must meet.
  • A rough expected duration, and which milestone this is if the work was split.
  • Where the work is landing: the worktree path and branch, or that it is running in place.
  • How to watch progress without waiting on Claude.

Codex appends a live rollout log for every session under ~/.codex/sessions/YYYY/MM/DD/rollout-<timestamp>-<threadId>.jsonl, recording each command it runs, each patch it applies, and its own interim messages. Give the user this command to follow the newest session as it happens:

tail -f "$(ls -t ~/.codex/sessions/$(date +%Y/%m/%d)/rollout-*.jsonl | head -1)" | jq -r 'if .payload.type=="function_call" then "$ " + ((.payload.arguments|fromjson).cmd // ""|split("\n")[0]) elif .payload.type=="message" and .payload.role=="assistant" then "> " + ([.payload.content[]?|select(.type=="output_text")|.text]|join(" ")|split("\n")[0]) elif .payload.type=="patch_apply_end" then "* patch applied" elif .payload.type=="task_complete" then "* DONE" else empty end'

Adjust the path if CODEX_HOME is set. If jq is unavailable, point the user at the raw file instead of inventing a substitute.

Start the Codex task

These parameters apply whether Claude calls mcp__codex__codex directly or a courier subagent makes the call. Call it once per milestone, not once per project. Use:

  • cwd: the absolute worktree path when one was created, otherwise the absolute project root.

Match Codex's filesystem access to the current Claude Code session:

  • If Claude Code is read-only or in plan mode, use sandbox: read-only.
  • If Claude Code can write only within the current workspace, use sandbox: workspace-write.
  • If Claude Code has unrestricted filesystem access, use sandbox: danger-full-access.

Do not give Codex broader or narrower filesystem access than Claude Code currently has. Never add writable paths that are unavailable to Claude Code. Keep behavioral restrictions, such as a review-only task making no edits, in the task packet rather than changing the filesystem permission level.

Use approval-policy: never. Nobody can answer an approval prompt during a blocking MCP call, so a policy that can request one risks stalling the session indefinitely. Express behavioral limits as instructions in the task packet and as the sandbox level above, never as an approval tier. Do not override the Codex model or reasoning configuration unless the user asks or the current task has a documented need.

Save the returned threadId. Treat Codex's summary as a handoff, not proof of correctness.

If the call stalls or fails

When the tool errors, returns nothing useful, or the session is interrupted, Claude never receives a threadId — but the work may have partly landed. Recover from the rollout log rather than restarting blindly:

  1. Find the session: the newest ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl. The threadId is the trailing UUID in the filename.
  2. Read it to establish what Codex actually ran and changed, and compare against the baseline.
  3. Continue with mcp__codex__codex-reply using that threadId, stating what is already done and what remains.

Report a stall to the user as a stall. Never present a partially applied change as a completed delegation.

Review the result

After Codex returns:

  1. Inspect the actual working tree against the baseline. Use git diff and git status in a repository; outside one, diff the file listing captured earlier and read the changed files directly.
  2. Confirm the changed files are within scope.
  3. Verify acceptance criteria one by one.
  4. Review correctness, edge cases, error handling, security, compatibility, and unnecessary complexity.
  5. Check test output or run proportionate verification yourself.
  6. Distinguish pre-existing failures from regressions caused by the change.

Write only actionable findings:

  • P0: unsafe to continue or ship.
  • P1: material correctness, security, data-loss, or requirement failure.
  • P2: worthwhile maintainability or coverage issue.

Include the file and location, evidence, impact, and a verifiable correction. Do not create a review loop over taste, wording, or equivalent implementation choices.

Continue the same thread

If correction is needed, call mcp__codex__codex-reply with the saved threadId. Send:

  • The exact findings to address.
  • Any new failing command or evidence.
  • The behavior that must remain unchanged.
  • The validation Codex must rerun.

Call it from the main session, including when the original call was made by a courier subagent — the thread is server-side and keeps its context across that boundary, so there is no reason to spawn a second courier for a correction.

Use the same thread rather than starting a fresh Codex task. Allow at most two correction rounds unless the user explicitly requests deeper iteration. If two rounds do not converge, stop the ping-pong, summarize the disagreement and evidence, and ask the user only if a material decision is required.

Land the change

Claude owns the merge. Codex produced a candidate on a branch; deciding it is good and integrating it is the acceptance owner's job, not the user's chore and not Codex's call. Once acceptance passes, merge without asking — a local merge is reversible, and the codex/<slug> branch remains as an escape hatch.

Merge only when all of these hold. These are Claude's own checks, not questions for the user:

  1. Every acceptance criterion is verified, and no P0 or P1 finding is open.
  2. Claude ran the validation itself, not merely read Codex's report of it.
  3. The base branch has no uncommitted changes that the merge would disturb. If it does, stop and tell the user what is in the way rather than stashing or overwriting their work.

Then:

  • Codex is normally told not to run git commands, so its work sits uncommitted in the worktree. Commit it on codex/<slug> from the worktree first, with a message that states what changed and records the Codex threadId for provenance.
  • Merge into the base branch. Fast-forward when the base has not moved; otherwise --no-ff so the delegation stays legible in history.
  • Rerun the validation on the merged result. A suite that passed inside the worktree can still fail after integration.
  • Remove the worktree with git worktree remove once merged. Keep the branch until the user says otherwise.

Still requires explicit user authorization, because these reach past the local repository or destroy work:

  • git push, opening a pull request, publishing, deploying, or tagging a release.
  • Any force operation, history rewrite, or hard reset on a branch the user shares.
  • Discarding the user's uncommitted changes for any reason.
  • Merging when acceptance did not pass, including "it's close enough" and "the failure looks pre-existing".

Report the merge as part of the final answer: what was merged, into what, and the post-merge validation result.

Protect the workspace

  • Keep a single writer for each worktree at any moment. A dedicated Codex worktree is the cheapest way to guarantee this.
  • Never let Claude and Codex edit the same files concurrently. While a delegation is in flight, Claude reads and verifies; it does not edit the delegated files.
  • Parallelize only independent read-only investigations or work isolated in separate worktrees.
  • Preserve unrelated user changes.
  • Committing and merging an accepted delegation is Claude's job, under the conditions in "Land the change". Pushing, publishing, deploying, opening a pull request, and any destructive or history-rewriting operation still require the user to ask for it.
  • Do not broaden scope merely because either agent suggests adjacent cleanup.

Finish

Claude remains responsible for the final answer. Report:

  • What Codex did and what Claude independently verified.
  • Files or behavior changed.
  • Commands or checks run and their outcomes.
  • Review findings fixed or intentionally deferred.
  • Where the work now lives: merged into which branch, or still on codex/<slug> and why it was not merged.
  • Remaining uncertainty or risk.

Never claim cross-model verification occurred when the Codex tool did not run successfully.