claude-codex-forge

Run Claude Code and OpenAI Codex as one team — two models from two labs, producing output stronger than either alone.

Most Claude↔Codex projects ship plumbing (an MCP wrapper, a dialog bridge). This ships the workflow: an opinionated pair system where each task is routed to the better-suited agent, the other attacks the result adversarially, and the conductor synthesizes the best of both — with the receipts to prove nothing got rubber-stamped.

Why cross-model? Asking the model that wrote your code to review it is asking someone to grade their own homework. Research on multi-agent systems is blunt about it: same-model debate mostly collapses into self-consistency, while cross-model dissent grounded in actually running code is where the measured gains are. That's the whole design here.

What's in the box

Piece	What it does
bin/codex-ask	One-shot Codex second opinion on any directory — no git repo needed. --verdict forces a structured PASS/CONCERNS/BLOCK ruling, --diff reviews your actual git diff, --resume continues the same Codex thread across rounds.
bin/codex-build	Dispatch Codex as a builder (write mode) with a role guard, optional git-worktree isolation, and a mandatory self-verification block.
bin/codex-bg	The only one that backgrounds: fire Codex jobs, keep working, collect answers later. Ships a hard circuit-breaker (max concurrent jobs, wall-clock kill, token warnings) so agents can't run away with your quota.
skills/forge/	The /forge Claude Code skill — the full power-team loop: route by failure mode → lead attempt → adversarial dissent → synthesis brief → loop while improving.
codex/	Drop-in Codex configuration: a role-neutral AGENTS.md, builder + reviewer personas, and three skill packs (verification honesty, code quality/security, current-docs discipline).
hooks/	Optional Claude Code Stop hook that fires a background Codex review after substantial edit turns. Never blocks your terminal (some review gates block for 15 minutes; this one never does). Off by default.

The rules that make it a team (not two agents taking turns)

These came out of real adversarial review between the two models, not theory:

• Route by failure mode, not identity. Claude leads direction/architecture/prose; Codex leads implementation/debugging/verification. Invert when the usual lead lacks the decisive evidence.
• Dissent is independent. The non-lead attacks the attempt against explicit success criteria — fresh context, no access to the author's reasoning, so it can't be charmed into agreement.
• Synthesis is accountable. Every major critique ends up accepted / rejected-with-evidence / open — silent drops are forbidden, and "I disagree" is not a rejection. Critiques are judged on evidence, not on which model said them.
• Loop while improving, not until PASS. "Loop until the reviewer says PASS" is guardrail theater. PASS is evidence, not the goal.
• PASS is earned. A reviewer may only return PASS if it actually ran something this pass (build/test/execute), or states exactly why nothing was runnable. Read-only glances max out at CONCERNS.
• Verify the artifact, never the claim. A read-only agent can print a plausible diff and a green test against the OLD file. After any apply: grep the change is on disk and run the test yourself.

Install

git clone https://github.com/JDiz00/claude-codex-forge ~/claude-codex-forge
cd ~/claude-codex-forge && bash setup.sh

Requirements: the OpenAI Codex CLI (npm install -g @openai/codex, then codex login — works with a ChatGPT subscription or API key), git, python3, macOS or Linux. On macOS also brew install coreutils (for timeout — without it the tools still run, but the stall guard and wall-clock circuit-breaker are disabled). Claude Code for the /forge skill and the optional hook; the three bin/ tools also work standalone from any terminal.

setup.sh is idempotent: it puts bin/ on your PATH, offers to copy the /forge skill into ~/.claude/skills/, and prints (never performs) the optional Codex persona and hook setup. It does not edit your Claude or Codex settings for you.

Quick start

# a second opinion on anything, no repo required
codex-ask "GOAL: sanity-check this design. QUESTION: what breaks first under load?" ./docs --high

# a real review with teeth: structured verdict, run-backed PASS, your actual diff
codex-ask "review this change" . --verdict --diff

# Codex writes code, isolated in its own git worktree
codex-build "add retry logic with backoff to the fetch layer" . --worktree

# fire-and-forget background jobs with a circuit-breaker
codex-bg start "audit this codebase for security issues" . --high
codex-bg jobs
codex-bg last <jobid>

And inside Claude Code, for the tasks where quality matters more than speed:

/forge design the caching layer — don't get this wrong

The circuit-breaker (why you won't get surprise usage)

Codex on a subscription bills quota, not per-token dollars — so the runaway risk is too many jobs, jobs that never end, quota burn. codex-bg refuses to launch past sane limits and kills runaways. All overridable:

Env var	Default	What it does
CBG_MAX_ACTIVE	3	max jobs running at once
CBG_MAX_TOTAL	12	max launches before it makes you reset
CBG_MAX_JOB_SECONDS	3600	hard wall-clock per job (kills runaways)
CBG_TOKEN_WARN	1500000	warn past this many cumulative tokens
CBG_TOKEN_HARD	0 (off)	hard-stop past this many tokens

codex-bg budget shows the tally; codex-bg budget --reset zeroes it.

State & privacy

All runtime state lives under ~/.claude-codex-forge/ (override with CODEX_BG_ROOT). These tools add no telemetry of their own — but they are wrappers around the Codex CLI, so your prompts and file context still go to OpenAI (and to Anthropic when Claude Code runs), exactly as when you use those CLIs directly. The local job logs, session ids, and ledger never leave your machine.

Going deeper

This repo is the complete mechanism, free. If you want the full setup playbook — the exact end-to-end configuration, the handoff-brief templates, and the workflows this system was distilled from — it's available as a paid guide: Setup Playbook ($29). Everything in this repo works without it.

All my Claude Code tools: expressive446.gumroad.com

License

MIT.

---

Claude is a trademark of Anthropic PBC. This project is not affiliated with, endorsed by, or sponsored by Anthropic. Codex is a product of OpenAI; this project is likewise not affiliated with OpenAI.