paircode

Multi-LLM peer review for your code, with file-traces on disk. One primary LLM (alpha, usually Claude Code) + any number of peer LLMs (Codex, Gemini, Ollama, …) running research / plan / execute / ask cycles with structured cross-review rounds stored entirely as Markdown on disk.

Born from 31 iterations of dual-LLM silent-agreement hunting on a real ML project. See diary/001-step-a-architecture.md for the origin story and diary/003-arch-b-pivot-grappling.md for the current (v0.11) team-lead architecture.

Install

pipx install paircode       # or: pip install --user paircode
paircode install            # registers /paircode in every detected LLM CLI

paircode install deploys /paircode into each LLM CLI it finds on your PATH:

In Gemini you may need /commands reload the first time. In Codex the marketplace fetches on first use.

paircode delegates LLM subprocess invocation to cliworker — that's where speed flags, MCP strip tricks, skip-cache, and subscription-first fallback live. paircode adds the peer-review orchestration on top (file-traces, stages, rosters, convergence).

Use it

Inside any LLM CLI that has /paircode installed, just type:

/paircode "build a KISS PHQ-9 depression risk engine"

or

/paircode "review my auth middleware approach at src/auth/"
/paircode "plan the refactor" --peers codex,gemini
/paircode "get a second opinion on this PR" --peer gemini

The slash command's team-lead prompt (the LLM you're inside) reads your prompt, picks a stage (research | plan | execute | ask), fires peers, collects their markdown, iterates through review rounds until convergence, and writes consensus.md at the end. Everything lands under .paircode/ in your current project.

What ends up on disk

your-project/
  .paircode/
    JOURNEY.md                    # fleet log
    peers.yaml                    # roster: who's on the team
    sandbox/
      peer-a-codex/               # codex's persistent sandbox (code goes here)
      peer-b-gemini/              # gemini's persistent sandbox
    focus-01-<slug>/
      FOCUS.md                    # this focus's prompt + metadata
      research/
        alpha-v1.md ... alpha-vN.md
        peer-a-codex-v1.md ...
        reviews/round-01-peer-a-codex-critiques-alpha.md
        alpha-FINAL.md
        peer-a-codex-FINAL.md
        consensus.md              # team-lead synthesis (last thing written)
      plan/         (same shape)
      execute/      (same shape)
      ask/          (same shape)
    focus-02-<slug>/
      ...

Code vs. reports. Files inside focus-*/ are markdown reports (opinions, plans, critiques, summaries of work). Actual code lives elsewhere:

• Peers code in their sandboxed workspaces at .paircode/sandbox/<peer-id>/ — persistent across focuses.
• Alpha codes directly in the project root (the real repo) — alpha is the project.

Stages

Stage is picked by the team-lead LLM based on the prompt:

The team lead can chain stages in one invocation: research → plan → execute → done. No hard round cap — the team lead converges when peers stop surfacing new signal.

Commands (the helper CLI)

Most users will only ever type paircode install and then use /paircode inside their LLM CLI. The binary's other commands are helpers the team-lead slash command calls on your behalf:

paircode                         print current .paircode/ state
paircode install                 register /paircode in every detected LLM CLI
paircode uninstall               remove /paircode from LLM CLIs (idempotent)
paircode ensure-scaffold         idempotent .paircode/ init + handshake (silent)
paircode focus new <slug>        create a new focus dir, print its path
paircode focus active            print the active focus path
paircode roster [--alpha <cli>] [--peer <id>] [--peers <id,id>]
                                 print peer ids, best-effort, never errors
paircode invoke <peer-id> "<prompt>" --out <path>
                                 fire one peer, write file-trace to --out
paircode converge <stage>        copy each participant's latest vN to *-FINAL.md

Model compatibility

Peer roster is auto-detected at first install via paircode handshake (silent, called by ensure-scaffold). Edit .paircode/peers.yaml to customize.

Why this exists

See diary/001-step-a-architecture.md. Short version: running two LLMs adversarially surfaces silent-agreement bug classes that neither engine alone catches — cross-engine agreement is not the same as correctness when both engines share a blind spot.

See diary/003-arch-b-pivot-grappling.md for why v0.11 moved orchestration out of a Python driver and into the slash-command's team-lead LLM.

License

MIT. See LICENSE.