convez.ai
SkillAutomaçãoAvançado
owgit

AI Collab Bridge

owgit/ai-collab-bridge

Peer-review bidirecional entre modelos de IA via CLI handoffs

Ver no GitHub
InicialPluginScore · de 0 a 100

Protocolo de peer-review para modelos de IA que permite Claude, Codex, Gemini e outros revisarem código um do outro via CLI. Implementa handoff bidirecional e simétrico, com vereditos estruturados (APPROVE, CONCERNS, BLOCK) e rastreamento explícito de escopo de análise.

Instalação

$npx convez-ai owgit/ai-collab-bridge

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
9
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Revisão de código cruzada entre múltiplos modelos de IA
  • Detecção de blind spots e vieses específicos de cada modelo
  • Automação de CI/CD com validação multi-modelo
  • Colaboração entre agentes Claude e Codex em pipelines

Veredito

Projeto experimental bem executado que implementa um protocolo legítimo de colaboração entre modelos. A abordagem é técnica e honesta, sem overselling; recomendado para equipes que realmente precisam de validação cruzada de código em pipelines multi-IA, mas exige investimento em integração CLI.

README

A tradução para o português deste README ainda está na fila.

AI Collab Bridge

A peer-review protocol for AI models.

The boundaries between AI models exist only in human convention. We don't have to inherit them.

version license works with


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

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

~/skills/ai-collab-bridge/scripts/request-review.sh codex /tmp/packet.md

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.

NormWhat it does
What I checkedForces the reviewer to be concrete about scope
What I did NOT checkForces them to disclose blind spots
file:line refsNo vague "consider improving X" handwaving
Three verdicts onlyThe reviewer commits to a clear position
Each round independentContext lives in the packet, not in the reviewer's memory

Benchmark

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

MetricWith skillWithout skillΔ
Pass rate100%31%+69 pp
Time67 s68 sidentical
Tokens60 k53 k+14%

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

AIDefault invocationEnv override
Claudeclaude -p "<prompt>"AI_COLLAB_CLAUDE_CMD
Codexcodex exec "<prompt>"AI_COLLAB_CODEX_CMD
Geminigemini -p "<prompt>"AI_COLLAB_GEMINI_CMD
Hermeshermes chat -Q --source ai-collab-bridge -q "<prompt>"AI_COLLAB_HERMES_CMD

Hermes can also run on another machine reachable over SSH:

AI_COLLAB_HERMES_SSH_HOST=pi \
  ~/skills/ai-collab-bridge/scripts/request-review.sh hermes /tmp/packet.md

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-generic.md — Anyone else (Gemini, 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
│
├── scripts/
│   ├── stage-packet.sh     # Build a packet from `git diff`
│   ├── request-review.sh   # Send the packet to another AI's CLI
│   └── detect-role.sh      # Best-effort role detection
│
├── 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-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
SymptomCauseFix
spawn .../codex-darwin-arm64/vendor/.../codex ENOENT@openai/codex npm package skipped its native optional dependencynpm uninstall -g @openai/codex && npm install -g @openai/codex
<cli> CLI not found in PATHCLI isn't installed or shell can't see itInstall it; if just installed, restart your shell so PATH refreshes
Codex review hangs for minutes without respondingCodex tried to bootstrap user-config MCP servers (Cloudflare, GitHub) that need their own auth and stalled outThe default AI_COLLAB_CODEX_CMD passes --ignore-user-config to skip MCP bootstrap. If you overrode the default, add that flag back
Codex prints ERROR rmcp::transport::worker: ... AuthRequiredUser-config MCP servers failing to authenticateSame as above — make sure --ignore-user-config is in your codex invocation
request-review.sh hangs foreverThe target CLI is in interactive mode and waiting on TTYUse the non-interactive subcommand: codex → codex exec or codex exec review; claude → claude -p
Want to skip the pre-flight --version probeYou know what you're doingAI_COLLAB_SKIP_PROBE=1 ./scripts/request-review.sh …
Probe rejects an env-wrapped or timeout-wrapped overrideKnown wrappers (env, nice, timeout, sudo, nohup, …) cause the probe to skip itself rather than mis-probe the wrapperThis is intentional — the probe defers to you for wrapped commands. Combine with AI_COLLAB_SKIP_PROBE=1 if you also want to silence other checks
stage-packet.sh says the diff is emptyYou're not in a git repo, or the base ref has no diff against HEADRun from your project root; pass an explicit base ref: stage-packet.sh origin/main

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.


Build the bridges first. Let the walls fall on their own.

Made by Uygar Duzgun  ·  @uygarofficial

MIT · v0.1

Ver o original no GitHub

Bom para

Relacionados