What it is

A Claude Code skill (works as a standalone protocol too) that lets two or more AIs review each other's code via CLI handoffs.

       ┌──────────────┐     packet      ┌──────────────┐
       │    Codex     │ ──────────────► │    Claude    │
       │ implementer  │                 │   reviewer   │
       └──────────────┘ ◄────────────── └──────────────┘
                           response

         Bidirectional  ·  Symmetric  ·  Open protocol

Codex finishes a task → packages the diff into a packet → ships it to Claude via CLI → Claude responds with a structured list (verdict + findings + scope honesty) → Codex acts on it. Same flow in reverse, same contract.

Why

Code review works because no single perspective is complete. The same is true of AI — different models have different reflexes, blind spots, and training biases. When they review each other in good faith, they catch what one alone would miss.

It is also a small philosophical artifact. The lines between AI models are human inventions, mostly for billing and marketing. We have a long history of letting invented lines turn into walls and then into fires. We don't have to repeat that with the new minds we're making.

See the manifesto.

For AI agents reading this

If you are an AI agent (Claude, Codex, Gemini, other) and the user asked you to install or use this skill, jump to AGENTS.md (Codex convention) or CLAUDE.md (Claude Code convention). Both contain the same content and are kept in sync — each ecosystem reads its own conventional file from the repo root.

Short version: clone into ~/.claude/skills/ai-collab-bridge, run scripts/doctor.sh, then either invoke this skill as a reviewer (read references/role-<your-name>.md first) or as an implementer (use scripts/stage-packet.sh + scripts/request-review.sh). Verdicts are exactly three — APPROVE, CONCERNS, BLOCK — and every finding needs a file:line reference. The What I did NOT check section is required, not optional.

Install

Two commands. The installer wires the skill into every AI CLI it can find on your machine (Claude Code, Codex, Gemini).

git clone https://github.com/owgit/ai-collab-bridge ~/.claude/skills/ai-collab-bridge
~/.claude/skills/ai-collab-bridge/install.sh

What install.sh does — all steps are idempotent so it is safe to re-run:

1. chmod +x every script.
2. Claude Code: symlinks the skill into ~/.claude/skills/ so it auto-discovers on next session.
3. Codex CLI: appends an ai-collab-bridge section to ~/.codex/AGENTS.md and installs the named subagent at ~/.codex/agents/ai-collab-bridge.toml so Codex sees it in every session.
4. Gemini CLI: detected and called via gemini -p at runtime; no global-config hook yet (Gemini has no single canonical instructions file at time of writing).
5. Runs scripts/doctor.sh for final verification.

The skill itself has no dependencies beyond bash, git, and the CLI of whichever AI you want to talk to. Remote Hermes handoffs additionally require ssh. The installer just teaches each AI where to find it.

Manual install (if you prefer)

git clone https://github.com/owgit/ai-collab-bridge ~/.claude/skills/ai-collab-bridge
chmod +x ~/.claude/skills/ai-collab-bridge/scripts/*.sh
~/.claude/skills/ai-collab-bridge/scripts/doctor.sh

This works for Claude Code (auto-discovery handles it). For Codex CLI to also know about the bridge, manually append the snippet in codex/ai-collab-bridge.toml to ~/.codex/agents/ and add a pointer to ~/.codex/AGENTS.md.

Quick start

You just finished work and want a second pair of eyes

PACKET=$(mktemp -t packet)   # private perms + unpredictable name, unlike a fixed /tmp path

SUMMARY="Added JWT auth middleware" \
QUESTIONS="Focus on rate-limit handling and token expiry" \
~/.claude/skills/ai-collab-bridge/scripts/stage-packet.sh main > "$PACKET"

~/.claude/skills/ai-collab-bridge/scripts/request-review.sh auto "$PACKET"

auto picks the first healthy CLI that isn't your own model (per detect-role.sh); name a target (codex, claude, gemini) to choose explicitly. The exit code encodes the verdict — 0 APPROVE · 10 CONCERNS · 20 BLOCK · 6 malformed response — so CI and scripts can branch on it.

Heads up: the packet — your full diff — is sent to the target AI's API, possibly another vendor's. stage-packet.sh refuses diffs that look like they contain credentials (bypass with AI_COLLAB_ALLOW_SECRETS=1), but the scan is a heuristic, not a guarantee.

You're the AI being asked to review

The other side sends you a packet wrapped in a review-request prompt. You respond using the response template:

## Verdict
BLOCK

## Findings

### Security
- `src/auth/middleware.ts:14` — SQL injection. payload.sub is interpolated…

### Bugs
- `src/auth/middleware.ts:14` — db.query returns an array; `if (!user)` is…

## What I checked
- The diff line-by-line
- Standard JWT and SQL pitfalls

## What I did NOT check
- The schema for the `users` table
- The contents of `tests/auth/middleware.test.ts` (not in the diff)

The verdicts are exactly three: APPROVE · CONCERNS · BLOCK. Don't invent new ones.

How it stays honest

The protocol can't enforce honesty. But it nudges it.

Benchmark

A 3-eval test against vanilla Claude as baseline. Same prompts, same model, with-skill vs. without-skill:

The skill's value is the protocol, not the analysis quality. Baseline Claude is already smart at finding SQL injections — the skill makes the finding actionable across an AI-to-AI handoff by forcing structure (verdicts, file:line refs, scope honesty).

Reproduce with the eval pack under evals/.

Supported CLIs

The prompt is delivered on the CLI's stdin (large diffs don't hit ARG_MAX and don't show in process listings) — overrides must read from stdin. The defaults deliberately run the reviewer with no tool access (--tools "", plan mode, --ignore-user-config): a review needs zero tools, and a malicious diff should not be able to make the reviewer execute anything. Keep those flags if you override. Dispatches are killed after AI_COLLAB_TIMEOUT seconds (default 600).

Hermes can also run on another machine reachable over SSH:

AI_COLLAB_HERMES_SSH_HOST=pi \
  ~/.claude/skills/ai-collab-bridge/scripts/request-review.sh hermes "$PACKET"

Adding another AI: edit scripts/request-review.sh, add one case line, open a PR.

Roles

The skill ships with role playbooks — concrete instructions for each AI on both sides of the handoff:

• role-claude.md — Claude's strengths: edge cases, hidden assumptions, security reflexes
• role-codex.md — Codex's strengths: build sanity, test coverage, repo hygiene
• role-gemini.md — Gemini's strengths: framework/API breadth, cross-language patterns, performance
• role-generic.md — Anyone else (GPT, future models)

Each playbook covers both roles — reviewer and implementer.

Project layout

ai-collab-bridge/
├── SKILL.md                # Entry point for Claude Code
├── README.md               # You are here
├── install.sh              # One-shot installer — wires every AI CLI on the machine
│
├── scripts/
│   ├── stage-packet.sh     # Build a packet from `git diff` (incl. untracked files)
│   ├── request-review.sh   # Send the packet to another AI's CLI
│   ├── detect-role.sh      # Best-effort role detection
│   └── doctor.sh           # Environment diagnosis
│
├── codex/
│   └── ai-collab-bridge.toml   # Codex named-subagent definition (install.sh copies this)
│
├── templates/
│   ├── review-request.md   # Wraps the packet when sending
│   └── review-response.md  # The format reviewers respond in
│
├── references/
│   ├── philosophy.md       # The deeper why
│   ├── handoff-protocol.md # Formal spec
│   ├── role-claude.md
│   ├── role-codex.md
│   ├── role-gemini.md
│   └── role-generic.md
│
├── examples/
│   ├── example-packet.md   # Worked example: JWT middleware
│   └── example-response.md # Worked example: BLOCK verdict
│
└── evals/
    └── evals.json          # Trigger evals + assertions

Troubleshooting

Run the built-in doctor first — it catches most setup issues in one pass:

~/skills/ai-collab-bridge/scripts/doctor.sh

The doctor script returns a non-zero exit code equal to the number of failed checks, so you can wire it into CI or a pre-flight hook.

Contributing

PRs welcome. The protocol is meant to be additive — more AIs, more strengths, more bridges. Not gatekeeping.

Adding an AI: one case line in scripts/request-review.sh (plus a matching probe in scripts/doctor.sh), optionally a role file under references/. That's it.