mcp-code-assistant-peers

Parallel peer review for CLI coding agents — fully live, no API keys required.

Translations: 한국어 | 日本語 | 中文

What it does

When you edit code with Claude Code, Codex, or Gemini, this MCP gate routes the diff to multiple independent peer reviewers running in background tmux sessions. Each reviewer checks the change from a fresh context, findings are saved to SQLite, and the host assistant reads all results directly — no redundant synthesis pass, no extra token cost.

Your coding session
  │
  ▼
Host edits code  →  must_call_after_code_changes
                          │
              ┌───────────┼───────────┐
              ▼           ▼           ▼
        codex-live   gemini-live  claude-live    ← parallel, tmux
              │           │           │
              └───────────┴───────────┘
                          │
                    All findings delivered
                    directly to host
                          │
                          ▼
              Host reviews findings & improves code

Why live mode?

Live vs Headless

Every reviewer defaults to live mode. You only need to log in once per CLI:

claude     # Claude Code login
codex      # Codex login
gemini     # Gemini CLI login — OAuth, no API key needed

No API keys. No credit pool charges. Reviews run on your subscription.

Review history (key advantage)

Live sessions keep conversation history by default. The reviewer builds up knowledge of your codebase across multiple reviews in the same session:

Review #1 → "This function lacks null checking" (learns the codebase)
Review #2 → "Good fix. The same pattern exists on line 42 too." (accumulated knowledge)
Review #3 → "Consistent with the null-check pattern you've been applying" (contextual)

Each session is scoped per (reviewer, repo) — reviewers for different repos are completely isolated.

To reset history between reviews (old behavior):

CODE_ASSISTANT_PEERS_REVIEWER_CLEAR=always

Quick start

# 1. Install
bun install

# 2. Auto-detect available CLIs and register MCP
bun cli.ts setup claude --peers=auto

# 3. Verify
bun cli.ts doctor

Inside Claude Code or Codex, make any code change — the review gate triggers automatically.

Default configuration

Everything is pre-configured for live mode:

Review modes

CODE_ASSISTANT_PEERS_REVIEW_MODE=adversarial

Peer workflow modes

CODE_ASSISTANT_PEERS_WORKFLOW=peer_fix

Architecture

Review flow

First review in a session
  │
  ▼  Worker creates tmux session → CLI boots (one-time)
  │
  ▼  Review job delivered to session
  │    ├── Reviewer writes .peer-review/<id>-output.md  (primary path)
  │    └── Reviewer also prints to terminal              (fallback)
  │
  ▼  Worker reads result → broker → MCP → host
  │
  ▼  Session stays alive with full history

Next review (same repo)
  │
  ▼  Session already warm — no cold start — instant delivery

Session isolation

Each live session is scoped to (reviewer_kind, repo_path):

peer-reviewer-claude-<repo>-<hash>
peer-reviewer-codex-<repo>-<hash>
peer-reviewer-gemini-<repo>-<hash>

Watch a live session:

tmux ls                                              # list all sessions
tmux attach -t peer-reviewer-gemini-myrepo-abc123   # watch gemini think

No aggregate pass

Peer results go directly to the host — no intermediate synthesis:

Before: peers → aggregate LLM call → host   (extra tokens, extra latency)
Now:    peers → host directly               (zero overhead)

The host reads each reviewer's findings and decides what to fix.

Setup

Auto-setup (recommended)

bun cli.ts setup claude --peers=auto

# With options
bun cli.ts setup claude --peers=auto --workflow=peer_fix --mode=adversarial

Manual peer selection

# All three live reviewers
bun cli.ts setup claude --peers=claude-live,codex-live,gemini-live

# Codex only
bun cli.ts setup claude --peers=codex-live

Environment variables

Security

Each live session restricts file writes to .peer-review/ only:

Shell execution (run_shell_command) is hard-denied for gemini-live, preventing prompt-injection via sed -i, shell scripts, etc.

Custom adapters

Register any CLI that accepts prompts through stdin or argv:

{
  "my-llm": {
    "id": "my-llm",
    "command": ["my-llm-cli", "--model", "best", "-"],
    "prompt_transport": "stdin",
    "description": "My custom LLM CLI"
  }
}

CODE_ASSISTANT_PEERS_ASSISTANTS='{"my-llm": {...}}' bun server.ts
PEER_ASSISTANTS=my-llm bun server.ts

MCP tools

Typical flow

1. begin_peer_task                  ← before editing
2. [make code changes]
3. must_call_after_code_changes     ← required after editing
4. wait_for_peer_review             ← repeat until reviewed / partial_failed
5. [read all peer findings, fix issues]
6. must_call_after_code_changes     ← if more edits were made

Troubleshooting

Session not starting

tmux ls | grep peer-reviewer               # list sessions
tail -f /tmp/code-assistant-peers-backend.log   # worker logs

Gemini login required

gemini   # Run once and complete OAuth login

Next review starts automatically. No API key needed — Gemini subscription covers it.

Claude billing: API vs subscription

The reviewer session must NOT have ANTHROPIC_API_KEY set. If it is set, Claude Code bills the API key regardless of interactive mode.

# In the reviewer environment, ensure this is unset:
unset ANTHROPIC_API_KEY

# Verify: launch claude and check it shows "Claude Team" or "Pro", not API key mode
claude

Reset review history for a repo

tmux kill-session -t peer-reviewer-claude-myrepo-abc123
# Next review creates a fresh session

Disable live mode (force headless)

CODE_ASSISTANT_PEERS_LIVE_HOST_REVIEWS=0   # host-side passes use headless
CODE_ASSISTANT_PEERS_REVIEWER_CLEAR=always  # clear history between reviews
PEER_ASSISTANTS=codex,gemini               # use headless adapters directly

Requirements

• Bun v1.1+
• tmux (for live sessions)
• At least one of: Claude Code CLI, OpenAI Codex CLI, Google Gemini CLI
• Logged in to each CLI you want to use as a reviewer