Codex × Claude Dual-Model Collaboration
Set the current model as primary, and the other CLI model as peer reviewer. The primary is responsible for the results; the peer provides independent judgment and does not co-edit the same worktree.
Core Invariant:
First verify "whether what is being done is what the user truly wants", then verify "whether the scheme and code are correct". It is not considered successful if both models agree on the same wrong contract.
The "collaboration" here refers to: the primary completes research, implementation and self-testing, the peer reads the same batch of original evidence to conduct independent challenge and verification, and the primary then revises according to the findings. The peer does not directly code in the shared worktree; this is exactly the generalization of the existing "Codex leads, Claude Code independently verifies" process by this Skill. If the user explicitly requires dual-model division of coding, an independent worktree must be used, and merge review must be listed as a separate task; the default mode cannot be reused for secret parallel writing.
0. Completeness and Efficiency Boundaries
"All products can use" means the Skill can be discovered and run across projects, not that every trivial task requires dual models. Trigger by proportion:
- Users explicitly require two models to collaborate, cross-validate or "revise until ACK": fully use this Skill.
- Complex solutions, cross-module development, migration, security, major refactoring, pre-release acceptance: proactively use this Skill.
- Low-risk, well-defined, easily rollback small fixes: completed by a single model by default; do not add four rounds of model calls for formality unless the user specifies.
Once this Skill is triggered, fully go through the four gates of Intent, Plan, Implementation, and Final; do not omit any for the sake of "speedup". High efficiency comes from:
- Automatically identifying the primary and selecting the other CLI;
- Unified handoff, schema and commands, preventing each project from reinventing prompts;
- Intent/Plan stopping wrong requirements or schemes early;
- Plan continuing from Intent, revision rounds continuing from Implementation, only cold-starting when anchoring is needed;
- Structured fail-closed, avoiding repeated manual judgment on half-finished outputs;
- Using state files to automatically determine the next gate, reducing manual session tracking and missed reviews.
The default
reasoning is the quality baseline for complete collaboration; only when the user explicitly prioritizes cost/time should it be lowered via environment variables, and this should be disclosed in the final result. 30 minutes is the failure upper limit, not the expected time consumption.
1. Role Selection
| Current Initiator | Peer | Invocation Parameters |
|---|
| Codex | Latest Claude Code Opus | |
| Claude Code | Current high-quality Codex configuration | |
| Uncertain | Let the script detect; explicitly specify if conflicts are detected | |
Use the Skill's
. The script uses argv + stdin to call the CLI, not shell concatenation; the peer runs in read-only mode with recursion protection enabled.
First perform command construction pre-check:
bash
python3 <skill-dir>/scripts/invoke_peer.py \
--peer auto \
--phase intent \
--cwd <project-root> \
--task-id <stable-project-task-id> \
--add-dir <external-evidence-dir> \
--prompt-file <handoff.md> \
--dry-run
If the CLI does not exist, is unauthenticated, times out, or does not return a structured conclusion, it is considered
; do not pretend dual-model review has been completed.
only proves parameters are assembled, not that the CLI can start, permissions are correct, or output is parsable. Completion evidence for any gate must come from real calls.
It is recommended to use
, where the wrapper puts the state into a persistent user state directory based on "project path hash + task id": macOS uses
~/Library/Application Support/CodePal/dual-agent-workflows/
, Linux uses
$XDG_STATE_HOME/codepal/dual-agent-workflows/
or
. All gates of the same task reuse a stable task id; different tasks must not reuse it. This does not pollute the repository, nor does it lose gates due to system cleaning of
or restart. Only when the integrator already has its own state storage should
be explicitly used. The state only stores verdict, session ID and report hash, not the handoff content.
2. Prepare Complete Handoff
Read references/handoff-template.md to provide a self-contained handoff for each gate. It must include:
- The user's original words and subsequent corrections, placed in the tag, must be quoted verbatim, not just the primary's summary.
- Expected business results, observable behaviors, out-of-scope items.
- Current facts and evidence paths; distinguish between facts, inferences, and assumptions.
- Project agreements, related code/documents, dirty worktree and permission boundaries.
- Deliverables of the current phase: scheme, diff, test results, migration drills or screenshots.
- Unverified content and questions that need peer challenge.
Give absolute paths or in-repository paths to the peer, allowing it to read original materials directly. The artifact manifest must contain at least one real absolute path. Do not only paste conclusions, nor imply "expected ACK" or disclose suspected bugs in the handoff.
Before sending evidence, check the project root's
,
, security/privacy documents and user constraints:
- If the user explicitly requires Claude and Codex to collaborate this time, it is considered permission to call both ends within the scope of the current task, but tokens, cookies, credentials and irrelevant personal data must still be excluded.
- If triggered proactively by the primary, when discovering restrictions on external models, single suppliers, confidentiality or data residency requirements, must first ask the user; do not call the peer without authorization.
- Keep the handoff as "the minimum dataset sufficient for complete review", prioritize controlled paths, do not copy irrelevant repository content.
Claude's reading boundary is
by default. When any evidence is outside the cwd, its parent directory must be explicitly passed:
bash
--add-dir /absolute/read-only/evidence-directory
Claude only opens
, so add-dir does not grant write capabilities. If the peer cannot read materials in the manifest, it must return
; do not continue to ACK after ignoring.
Codex's read-only sandbox restricts writing but allows reading absolute paths in the manifest, so there is no
parameter. During first installation or when the Codex CLI version changes, a real read probe must be done with temporary evidence outside the cwd; if it cannot be read, return
, do not assume behavior remains unchanged.
The wrapper will force check four machine tags:
text
<raw_user_request>...</raw_user_request>
<artifact_manifest>...</artifact_manifest>
<validation_evidence>...</validation_evidence>
<known_gaps>...</known_gaps>
Tags only prevent omissions, cannot judge whether content is honest; the primary must still ensure it contains original facts.
Final ACK cannot be obtained if any of the following are missing:
- User's original words;
- Acceptable product results;
- Key deliverable paths;
- Diff and validation evidence in the implementation phase;
- Known limitations and unfinished items.
3. Run Four Gates
Gate A: Intent
Before design or coding, let the peer independently answer:
- What does the user truly want, rather than what is literally requested?
- Which product assumptions are unvalidated?
- Will current boundaries cause "technically correct, but business invalid"?
- Which acceptance must use real data or user-visible behaviors?
bash
python3 <skill-dir>/scripts/invoke_peer.py \
--peer auto --phase intent --cwd <project-root> \
--task-id <stable-project-task-id> \
--prompt-file <intent-handoff.md>
When
, first revise the requirement contract. Do not start implementation. If the primary disagrees with findings, refute with original evidence and continue review, do not blindly follow the peer's authority.
Gate B: Plan
After Intent is ACKed, submit the accepted requirement contract, technical research and complete plan to the same peer session for continued review:
bash
python3 <skill-dir>/scripts/invoke_peer.py \
--peer <peer> --phase plan --cwd <project-root> \
--task-id <stable-project-task-id> \
--session-id <intent-session-id> \
--prompt-file <plan-handoff.md>
The plan must cover normal paths, failure paths, migration/rollback, privacy, security, performance, real data validation and test matrix. The peer must recheck against the user's original words, not just check internal consistency of the plan.
Gate C: Implementation
The primary independently codes, tests and records evidence. The peer does not modify files by default, avoiding shared worktree conflicts and responsibility ambiguity. Claude peer only opens
; Codex peer uses
sandbox_mode=read-only + approval_policy=never
. When
is needed, the primary pre-generates a read-only file and adds it to the artifact manifest.
After implementation is completed, start a new cold review session, do not continue from the Plan session to reduce anchoring effect. The handoff must include:
- Original requirements and accepted contract;
- Plan and change files;
- Readable path to complete ;
- Test commands, pass count and failure output;
- Real data/visual/migration evidence;
- What was not done and why.
bash
python3 <skill-dir>/scripts/invoke_peer.py \
--peer auto --phase implementation --cwd <project-root> \
--task-id <stable-project-task-id> \
--add-dir <diff-or-evidence-dir> \
--prompt-file <implementation-handoff.md>
The peer reports findings by P0/P1/P2/note. After the primary fixes them, use the implementation session ID to continue review, close old findings one by one, and request a fresh scan, do not only confirm the patch exists on the surface.
Gate D: Final
Enter final only when all the following conditions are met:
- Intent and Plan have been ACKed;
- Implementation has no unclosed P0/P1;
- The primary has completed necessary self-verification;
- User-visible results and real data have been verified;
- Out-of-scope items are not treated as "not needed by user";
- Unfinished items are clearly stated, no pretence of completion.
For high-risk tasks, mid-task requirement changes or when real acceptance has overturned the scheme, Final uses a new cold review session; otherwise, it can continue from the implementation session.
The wrapper uses
to automatically locate the state (or the integrator explicitly passes
), and the gate order is executed machine-wise:
- creates the workflow.
- only accepts ACKed intent, and must continue from the intent session.
- The first round of must be a new cold review session; revision rounds must continue from this implementation session.
- only accepts that intent / plan / implementation are all ACKed.
- Once a gate is ACKed, it cannot be overwritten; when the user corrects requirements, use a new state file and restart from intent.
Only three verdicts are accepted finally:
- : Contract and current phase evidence are sufficient, no blocking findings.
- : There are issues that need repair or redefinition of requirements.
- : Lack of evidence, permissions, CLI or user decision, unable to make honest judgment.
4. Handle Review Cycles
Each round follows:
text
peer finding
→ primary reviews with evidence
→ accepts and fixes, or rejects with evidence
→ primary self-tests
→ resumes the same review session to close items one by one
→ requests fresh scan
→ ACK / NOT_ACK / BLOCKED
Rules:
- The peer is not a voter; conclusions must be accompanied by files, behaviors or evidence.
- The primary cannot outsource testing responsibilities to the peer.
- Do not modify the same worktree in parallel. If peer coding is needed, an independent worktree must be used, and reviewed by the primary before merging; this is not the default.
- Do not write unfinished work as ACK due to token, time or CLI stuck issues.
- If the peer ends with tool request, plan or no verdict, it is considered unfinished; do not manually rewrite natural language fragments into ACK, repair the call or continue review to obtain a structured report again.
- When requirements are overturned by user acceptance, return to Gate A, old ACK automatically becomes invalid.
5. CLI Invocation and Continued Review
Script parameters:
text
--peer auto|claude|codex
--phase intent|plan|implementation|final
--cwd PROJECT_ROOT
--add-dir DIR # Repeatable; mandatory when Claude reads evidence outside cwd
--task-id ID # Recommended; automatically isolate persistent state by project and task
--state-file PATH # Advanced usage; choose one with --task-id
--prompt-file PATH # Choose one with --prompt / stdin
--prompt TEXT
--session-id ID # Continue review
--timeout-seconds 1800
--save-raw DIR # Only use when complete CLI events need to be saved
--dry-run
Output is unified JSON, at least containing:
json
{
"peer": "claude",
"phase": "implementation",
"sessionId": "...",
"verdict": "NOT_ACK",
"report": {
"summary": "...",
"findings": []
}
}
Original CLI events are not persisted by default, as they may contain project content. Only use
when the user explicitly needs complete review logs, and place the directory in a secure location.
Model selection:
- Claude uses alias + effort by default, enables safe mode, disables custom MCP, restricts to Read/Grep/Glob; on macOS, use to prohibit writing to cwd/evidence directories. Override with , .
- Codex uses the native configured model by default, and enforces reasoning; override with ,
DUAL_AGENT_CODEX_REASONING
- Do not hardcode full model version numbers that will expire. Report the actual model returned by the CLI or the requested model upon delivery.
6. Completion Conditions
When reporting to the user, clearly state:
- Who is the primary and who is the peer.
- Which gates were passed, and the final verdict of each gate.
- What the peer found, and how the primary handled it.
- What verification the primary ran on its own.
- Unfinished content or items requiring user acceptance.
If the primary determines a low-risk task does not trigger this Skill according to the proportion principle, must explicitly inform the user "dual-model review is not enabled for this task" and the reason, cannot let the user mistakenly assume collaboration has occurred.
During first installation or modification of this Skill, Final must also have these observable evidences:
- Codex primary → Claude peer completes real fresh and resume, and obtains structured verdict and state changes.
- Claude primary → Codex peer completes real fresh and resume, and obtains structured verdict and state changes.
- The contents of the central repository, Codex, and Claude Code directories are consistent.
- New CLI sessions of Codex and Claude Code can discover and trigger this Skill.
If any item only has dry-run, mock or "theoretically supported", cannot be written as completed.
Final handoff must put the absolute paths of the central source directory and the two actual installation directories into
entirely. When Claude peer reviews, pass
for each installation directory outside cwd, allowing the peer to compare file by file; if any directory is unreadable, return
.
The only criterion for "three copies consistent" is: after excluding
,
,
,
, compare the set of all relative file paths and the SHA-256 of each file; do not use directory size, mtime or sampling instead.
Installation or update adopts rollbackable order:
- Copy to a unique staging directory in the same parent directory of each target directory, and perform content comparison first.
- If the old version exists, atomically rename it to a unique backup; then atomically rename the staging to the official directory.
- Delete the backup only after both targets are verified consistent.
- If any target fails, restore the backup of all replaced targets, clean up staging, and re-perform three-party consistency check.
Do not directly overwrite a target directory in use, nor deliver in a semi-successful state.
This Skill comes with an atomic distribution script, run dry-run first then execute:
bash
python3 <skill-dir>/scripts/install_skill.py \
--source <central-skill-dir> \
--target <codex-skill-dir> \
--target <claude-skill-dir> \
--dry-run
Remove
to perform staging, comparison, replacement and rollback. The script excludes the above generated files, and finally outputs the SHA-256 of the unified content manifest.
The official structure check command for this Skill is:
bash
uv run --with pyyaml \
<skill-creator-dir>/scripts/quick_validate.py \
<dual-agent-collaboration-dir>
Expected output includes
; it only verifies the Skill structure, does not replace real CLI and new session discovery tests.
Do not say "both models agree, so it must be correct". Only say: two sets of independent reasoning have completed cross-review on complete evidence, and there are no known blocking items currently.