mcp-code-assistant-peers

Turn your coding agents into peer reviewers.

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

mcp-code-assistant-peers is an MCP review gate for CLI coding agents. Claude Code can implement a change, Codex can review it, findings are saved locally, and the host assistant is prompted to run a post-edit review gate before the final answer.

The GitHub repository is named code-assistant-peers; the package name remains mcp-code-assistant-peers.

Claude Code and Codex work out of the box. Gemini, GLM, DeepSeek, and other prompt-capable CLIs can be registered through adapter configuration.

User request
   |
   v
Host assistant edits code
   |
   v
mcp-code-assistant-peers MCP gate
   |
   +--> Peer reviewer CLI checks the diff
   +--> SQLite stores rounds, findings, status
   +--> Host fixes blocking findings before final response

Why This Exists

Single-agent coding workflows are fast, but the same model that wrote the patch can miss its own assumptions. This project makes review a local, repeatable workflow:

• one assistant writes the code,
• another assistant reviews the diff,
• findings are persisted across rounds,
• review gates always run asynchronously to avoid MCP host timeout failures,
• multiple peer CLIs can review the same change through PEER_ASSISTANTS.

Demo Scenario

Use this flow for a short demo video or terminal recording:

1. Ask Claude Code to implement a small feature with an intentional edge-case bug.
2. Claude calls must_call_after_code_changes.
3. Codex reviews the diff and reports a concrete finding.
4. Claude fixes the bug.
5. A second review passes with no blocking findings.

The smallest useful terminal demo is:

bun install
bun run setup
bun cli.ts doctor

Then, inside Claude Code or Codex, make a code change and ask the assistant to verify it with the MCP review gate.

Features

• CLI assistant peer review routing with built-in Claude Code and Codex adapters.
• Custom assistant adapters for CLIs that accept prompts through stdin or argv.
• Mandatory post-edit gate tool with strong MCP descriptions.
• Review modes: normal, adversarial, gate, and collaborative.
• Optional peer_fix workflow where the reviewer proposes concrete fixes without editing files.
• SQLite-backed task memory, review rounds, findings, and async status.
• Async-first review flow that avoids long blocking MCP tool calls.
• Setup helpers for MCP registration and local assistant checks.
• Project rule installer for CLAUDE.md and AGENTS.md.

Differentiators

Unlike single-model review plugins, this project is built as a local MCP workflow:

• Bidirectional: Claude can review Codex work, and Codex can review Claude work.
• Extensible: any CLI that accepts prompts through stdin or argv can be registered.
• Persistent: review rounds, findings, and task state are saved in SQLite.
• Gate-oriented: tools are described as mandatory post-edit gates for coding assistants.
• Multi-peer: PEER_ASSISTANTS=claude,codex,gemini fans review out to available peers.
• Async-first: post-edit gates start background reviews, then hosts poll SQLite status before the final answer.

Requirements

• Bun
• Claude Code CLI: claude for the built-in Claude adapter
• OpenAI Codex CLI: codex for the built-in Codex adapter
• Optional additional LLM CLIs such as Gemini, GLM, or DeepSeek
• A trusted local project where the MCP client is allowed to start stdio servers

Install dependencies:

bun install

Run local checks:

bun run check

Install From Npm

The package is published as mcp-code-assistant-peers on npm. Install Bun first because the package binaries run through #!/usr/bin/env bun:

curl -fsSL https://bun.sh/install | bash
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"

Then install the package globally before running setup, so MCP registration points to a stable package path:

npm install -g mcp-code-assistant-peers
code-assistant-peers status

Configure one MCP client with the npm-installed package. Choose only the block for the client you use.

For Codex:

code-assistant-peers setup codex --peers=auto

For Claude Code:

code-assistant-peers setup claude --peers=auto

Then restart the configured MCP client and call code_assistant_peers_setup from that client to verify the registered server.

One-shot usage is also possible for read-only commands such as status, but do not use npx for setup because MCP registration needs a stable installed server path:

npx mcp-code-assistant-peers status

Quick Start

The easiest path is the setup command. From a source checkout:

bun install
bun run setup

Or run the shell wrapper:

sh scripts/setup.sh

By default this registers the MCP server for both Claude Code and Codex with review_only, normal mode, and a 600 second Codex MCP tool timeout.

For a web-friendly one-line setup that also verifies Serena registration and patches Codex's MCP timeout, use:

curl -fsSL https://raw.githubusercontent.com/AnamKwon/code-assistant-peers/main/scripts/web-setup.sh | sh

The web setup script clones the project into ~/mcp-code-assistant-peers when needed, runs bun install, registers Codex by default, enables serena-auto when Serena or uvx is available, patches Codex to a 30 minute MCP timeout, and prints the relevant config lines. Useful variants:

# Use an existing checkout and set Codex MCP timeout to 30 minutes
sh scripts/web-setup.sh --dir /path/to/mcp-code-assistant-peers --timeout=1800

# Register both Claude Code and Codex when both CLIs are installed
sh scripts/web-setup.sh --target=both --timeout=1800

# Patch only Codex
sh scripts/web-setup.sh --target=codex --timeout=1800

# Detect installed peer CLIs and configure the available reviewers
sh scripts/web-setup.sh --target=codex --peers=auto

# Force Serena on, failing if neither serena nor uvx is available
sh scripts/web-setup.sh --serena=on

The built-in Claude setup command uses the POSIX env command, so the one-step setup flow is intended for macOS/Linux shells. Windows users should manually register the server with equivalent environment variables.

Common variants:

# Register only Claude Code
bun cli.ts setup claude

# Register both clients with reviewer fix proposals and compact gate reviews
bun cli.ts setup both --workflow=peer_fix --mode=gate

# Configure multi-peer review. Each host removes itself from this list at runtime.
bun cli.ts setup both --peers=claude,codex,gemini --mode=adversarial

# Let setup detect available Claude/Codex/Gemini reviewers.
# Gemini auto-selection requires GEMINI_API_KEY/GOOGLE_API_KEY.
# Use --peers=gemini to opt into Gemini CLI OAuth or Vertex credentials.
bun cli.ts setup codex --peers=auto

# Auto-enable Serena semantic context when serena or uvx is available
bun cli.ts setup both --serena=auto

# Force the standard diff/changed-files review flow
bun cli.ts setup both --serena=off

# Also install project rules into the current project
bun cli.ts setup both --install-rules

# Print the commands without changing local CLI config
bun cli.ts setup both --dry-run

setup uses --serena=auto by default. If it detects a local serena executable or uvx, it registers the MCP server with Serena available at review time:

• CODE_ASSISTANT_PEERS_CONTEXT_PROVIDER=serena-auto
• CODE_ASSISTANT_PEERS_DIFF_BUDGET=4000
• CODE_ASSISTANT_PEERS_SERENA_CONTEXT_BUDGET=8000

serena-auto does not call Serena for every review. At review time it checks the changed source file count, changed source byte size, diff truncation, and risky path names. The byte-size trigger uses filesystem metadata (stat) rather than reading full file contents. Small changes stay on the standard diff/symbol path; large or high-risk changes use Serena symbol/reference context. Lightweight symbol hints may still read changed source files to extract function/class names.

If Serena is not detected, setup leaves these variables unset and the review uses the standard changed-files/diff flow. Use --serena=off to force the standard flow, or --serena=on --serena-command='["serena","start-mcp-server","--project-from-cwd"]' to force a custom Serena command.

After setup, restart Claude Code/Codex and call code_assistant_peers_setup from the MCP client to verify runtime availability.

Manual Registration

Manual registration is still available if you want full control. Register the same server in each client with HOST_ASSISTANT and, when needed, PEER_ASSISTANT or PEER_ASSISTANTS.

Claude Code:

claude mcp add --scope user --transport stdio code-assistant-peers -- env HOST_ASSISTANT=claude bun /path/to/mcp-code-assistant-peers/server.ts

Codex:

codex mcp add code-assistant-peers --env HOST_ASSISTANT=codex -- bun /path/to/mcp-code-assistant-peers/server.ts

If installed globally from a registry, use the server binary instead of a local path:

claude mcp add --scope user --transport stdio code-assistant-peers -- env HOST_ASSISTANT=claude code-assistant-peers-server
codex mcp add code-assistant-peers --env HOST_ASSISTANT=codex -- code-assistant-peers-server

Verify the server can start:

env HOST_ASSISTANT=codex bun server.ts

Check installed dependencies from an MCP client by calling:

code_assistant_peers_setup

You can also run local diagnostics without opening an MCP client:

bun cli.ts doctor

doctor checks Bun, Claude CLI, Codex CLI, Gemini CLI, local review storage, and the recommended Codex MCP timeout.

Assistant Adapters

Claude, Codex, and Gemini are built in:

c