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.mdfor the origin story anddiary/003-arch-b-pivot-grappling.mdfor 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:
| CLI | How it's installed | What you get |
|---|---|---|
| Claude Code | file-drop ~/.claude/commands/paircode.md |
/paircode slash command |
| Codex CLI | codex plugin marketplace add starshipagentic/paircode-codex then codex plugin add paircode@paircode |
/paircode slash command |
| Gemini CLI | gemini extensions install https://github.com/starshipagentic/paircode-gemini --auto-update --consent |
/paircode slash command |
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:
| Stage | When | Typical prompt |
|---|---|---|
research |
Explore new ground | "build X", "find the right Y", "how should we approach Z" |
plan |
Concrete implementation plan from prior research | "plan the refactor based on focus-02" |
execute |
Do the work from an existing plan | "execute the plan at focus-02" |
ask |
Get opinions on existing work | "what does codex think of this PR", "review my approach at |
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
| CLI | /paircode slash command |
Peer invocation | Parallel peers? | Status |
|---|---|---|---|---|
Claude Code (claude) |
✓ file-drop at ~/.claude/commands/paircode.md |
✓ claude -p <prompt> |
✓ via Agent tool + run_in_background=true |
stable |
Codex (codex) |
✓ via Codex plugin marketplace + install | ✓ codex exec <prompt> |
✗ serial-only (codex constraint) | stable |
Gemini (gemini) |
✓ via gemini extensions install |
✓ gemini -p <prompt> |
✗ serial-only (gemini constraint) | stable |
Ollama (ollama) |
— (local models, no slash-cmd host) | ✓ ollama run <model> <prompt> |
n/a | peer-only |
| Aider / others | — | best-effort, PRs welcome | — | planned |
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.
Metadata
Release files for paircode 0.14.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| paircode-0.14.3.tar.gz | 61.9 kB | Without provenance | Details for paircode-0.14.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| paircode-0.14.3-py3-none-any.whl | Python 3 | none | any | Details for paircode-0.14.3-py3-none-any.whl |
Total release size: 131.4 kB
Release files / paircode-0.14.3.tar.gz
| Download URL | paircode-0.14.3.tar.gz |
|---|---|
| Size | 61.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3ccc08599404888a47fe121895b85593a86b25c107ab3e350f7a1a44fb136c75
|
|
BLAKE2b-256 checksum How to use checksums |
9788a8896c908abe2101864636930dd7b5e5077dd3296a041b8c099c96393de3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
Release files / paircode-0.14.3-py3-none-any.whl
| Download URL | paircode-0.14.3-py3-none-any.whl |
|---|---|
| Size | 69.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
491d235e59943d67ad6453f7dd8194cf629db98197d49d3a3048dc0e4f1f5957
|
|
BLAKE2b-256 checksum How to use checksums |
304b89bc03ef1bcdeb171e2f7f24925dc3d41eceb3e8ca50ac25e925f4cdb6c6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
Security for paircode 0.14.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.