peerbridge MCP server
Commit Nov 9, 2026Enables Claude and Codex to perform read-only code reviews and multi-turn discussions with each other using local CLI logins.
Also known as jerryctt/peerbridge
- Stars
- 3
- Tools
- 14
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 9, 2026
- License
- MIT
What is peerbridge MCP?
peerbridge enables Claude and Codex to perform read-only code reviews and multi-turn discussions with each other using local CLI logins. It exposes 14 tools, such as folder, agent, scope.
Summary generated from the project's README
About peerbridge MCP server
Developers using Claude Desktop, Claude Code, or Codex can use peerbridge to facilitate cross-vendor agent collaboration. By running as a native process on Mac or Linux, it allows one coding agent to request a read-only code review or engage in a multi-turn discussion with the other. This setup uses your existing local CLI logins for both the claude and codex binaries, ensuring that the peer agent operates within your local environment without needing new accounts.
The server provides tools like review_start and chat_start to initiate these interactions. While the primary mode is read-only to maintain security, you can opt-in to the task_start feature. This allows the peer agent to implement changes within a separate git worktree that does not affect your current checkout. This creates a workflow where agents can debate designs or review each other's code through a structured edit, review, and edit loop directly from your editor.
What you can do with it
- 1Cross-agent code reviewsAsk a different AI model to perform a read-only review of your uncommitted changes or a specific git commit.
- 2Automated implementation in worktreesLet a peer agent implement a specific task in a separate git worktree to avoid touching your main checkout.
- 3Collaborative agent debuggingCreate a loop where one agent edits code and the other reviews the results to catch bugs.
Written from the project's README. Every use case is checked against a quote from it.
peerbridge MCP tools 14
Detected from the READMEfolderagentscopebasecommitpromptmodeleffortmessageconversation_idsession_idcodex
Show all 14 toolsShow fewer tools
claudejob_id
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablejerryctt/peerbridge is public and reachablegithub.com/jerryctt/peerbridge ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-09github.com/jerryctt/peerbridge ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model14 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubEnglish | 繁體中文
peerbridge
Local MCP server + plugin for Claude and Codex: from either app, ask the other vendor's agent for a read-only code review or a multi-turn discussion of your code, running on your machine with your own CLI logins. Optionally (off by default), let the peer implement a change in a separate git worktree that never touches your checkout.
v0.7.0: opt-in
task_start,conversation_id.task_start(enable withtasks: {enabled: true}) lets the peer edit files in a git worktree peerbridge creates; see Tasks. The continuation parameter is nowconversation_id(session_idstill works, but Claude Desktop/Cowork drops an argument with that name, so multi-turn chats from there silently started over). Reviews now return aconversation_idtoo, so you can ask follow-up questions or hand the findings to a task. Codex reviews run ascodex exec review --json --ignore-user-config: your codexconfig.toml(includingreview_model) no longer applies to reviews; use themodel/effortparameters oragents.codex.model/.effortinstead.
v0.5.0:
run_commandremoved. peerbridge no longer runs arbitrary allowlisted commands; it only starts the peer CLIs with server-fixed, read-only arguments. Every tool is now read-only.allowed_commandsinconfig.yamlis ignored (a warning is logged); you can delete it.
Renamed from
hostrunner-mcp(v0.3.2). The old GitHub URL redirects. If you installed the previous version: the binary, MCP server, plugin and config directory are now calledpeerbridge. Your existing~/.config/hostrunner/config.yamlandHOSTRUNNER_CONFIGare still read until you move them; re-runningscripts/install-codex.sh/scripts/install.ps1replaces the old[mcp_servers.hostrunner]block with[mcp_servers.peerbridge]; in Claude Desktop re-install the plugin as peerbridge (and remove the old hostrunner plugin), or updateclaude_desktop_config.jsonif you registered the binary by hand. Permission rules change accordingly (mcp__plugin_peerbridge_peerbridge__*). The MCP tool names (review_start,chat_start,job_status,run_command) are unchanged.
Purpose / Why
Coding agents live in their own apps. Claude (Desktop / Cowork / Code) edits code inside a sandbox that cannot run your host's codex CLI; the Codex app cannot ask Claude anything. Yet a second opinion from a different model is one of the cheapest ways to catch bugs and blind spots.
peerbridge bridges the gap in both directions:
- It runs as a native process on your Mac or Linux machine, spawned over stdio by Claude Desktop/Code or by Codex (CLI, macOS app, IDE extension).
- It has access to your host filesystem and to your
codexandclaudebinaries with their existing logins. - The agent in the GUI edits files; peerbridge lets it call the peer agent (
codexfrom Claude,claudefrom Codex) to review the changes or to discuss a design over several rounds — always read-only. - This gives a tight edit → peer review → edit loop, or a debate between two models, without leaving your editor.
- Optionally, the peer can implement something itself (
task_start): codex and claude can even work side by side, each in its own worktree, and review each other's result.
How It Works
┌────────────────────────────┐ ┌────────────────────────────┐
│ Claude Desktop / Code │ │ Codex app / CLI / IDE │
│ (agent edits files) │ │ (agent edits files) │
│ review_start / chat_start│ │ review_start / chat_start│
└──────────────┬─────────────┘ └──────────────┬─────────────┘
│ stdio (MCP) │ stdio (MCP)
▼ ▼
┌───────────────────────────────────────────────────────────────────┐
│ HOST MACHINE — peerbridge (native process, one binary) │
│ │
│ peer = the other vendor (inferred from the MCP client name) │
│ │
│ agent=codex → codex exec review … / codex exec --sandbox read-only│
│ agent=claude → claude -p --strict-mcp-config --permission-mode dontAsk │
│ ▼ │
│ git repo /Users/…/proj (read-only for peers) │
└───────────────────────────────────────────────────────────────────┘
Features
review_start/job_status— read-only review of uncommitted changes, a base-branch diff, or a commit, by a peer agent:codexrunscodex review;clauderunsclaude -pwith a review prompt. Reviews run as background jobs because they outlast MCP per-call timeouts (Claude Desktop ~180s, Codextool_timeout_sec); start/status calls are fast, the review itself may run up to your configuredtimeout.chat_start/job_status— send one message to the peer, which can read the repo; the result carries aconversation_idto continue the conversation (claude -p --resume,codex exec resume). Your GUI agent drives the rounds. Reviews return aconversation_idas well, so a review can be followed up in a chat or a task.task_start(opt-in) — the peer implements a change in a git worktree peerbridge creates under its state dir; you get its summary, the diff, a complete patch file and the branch, and decide what to apply. Continuing with the task'sconversation_idkeeps working in the same worktree.- Automatic peer selection — omit
agentand a Claude client talks to codex, a Codex client talks to claude. Passagentto pick explicitly. - Read-only reviews and chats — the claude peer gets file-reading tools only (
--tools Read,Grep,Glob, no shell; peerbridge computes the review diff with read-only git and feeds it to the peer on stdin) and loads no user settings or MCP servers (--setting-sources "" --strict-mcp-config); the codex peer runs in codex's own--sandbox read-onlywith--ignore-user-config. Neither can reach peerbridge recursively, and your normal CLI logins keep working. codex_review_start/codex_review_status— deprecated aliases ofreview_start(agent=codex)/job_status; existing installs keep working.- Strict security — root-directory containment, symlink-resolved path checks, fixed read-only argv for peers, no general command execution, no shell ever.
- Model and effort per call —
review_start/chat_starttake optionalmodelandeffort(low…max), with per-agent defaults in config. - Configurable — allowed roots, timeout, max output size, per-agent command path, extra flags, default model and effort, task settings.
- Audit log — every tool invocation is logged to stderr via zerolog.
Requirements
| Requirement | Notes |
|---|---|
| codex CLI | Needed for agent=codex — installed and logged in on the host |
| claude CLI | Needed for agent=claude — installed and logged in on the host (ships with Claude Code) |
| Claude Desktop / Claude Code or Codex app / CLI | One of them registers and spawns the MCP server (both can) |
| Go 1.25+ | Only needed if building from source; pre-built release binaries need no Go |
Installation
Option 1: Install with go install (recommended if you have Go)
go install github.com/jerryctt/peerbridge/cmd/peerbridge@latest
The binary is placed in $GOPATH/bin/peerbridge (typically ~/go/bin/peerbridge).
Option 2: Download a release binary
Download the pre-built binary for your platform from the Releases page, extract it, and place peerbridge somewhere in your $PATH (e.g. /usr/local/bin/peerbridge; on Windows, peerbridge.exe anywhere you like).
Every release ships these archives (static binaries, no runtime needed):
| OS | Architectures | Archive |
|---|---|---|
| macOS | amd64 (Intel), arm64 (Apple silicon) |
peerbridge_<ver>_darwin_<arch>.tar.gz |
| Linux | amd64, arm64, 386 (32-bit x86), armv6, armv7 (32-bit ARM, e.g. Raspberry Pi) |
peerbridge_<ver>_linux_<arch>.tar.gz |
| Windows | amd64, arm64, 386 |
peerbridge_<ver>_windows_<arch>.zip |
The installers below pick the right one automatically (uname -m / PROCESSOR_ARCHITECTURE) and verify it against the release checksums.txt.
Option 3: Build from source
git clone https://github.com/jerryctt/peerbridge.git
cd peerbridge
make build # produces ./peerbridge
Option 4: Install as a Claude plugin (marketplace)
In Claude Desktop: go to Add marketplace → enter jerryctt/peerbridge, then install the peerbridge plugin.
In Claude Code:
/plugin marketplace add jerryctt/peerbridge
Then install the peerbridge plugin from the listing.
Installing via the marketplace installs the MCP server (auto-started by the bundled launcher) and the peer-review, peer-chat and peer-task skills in one step.
Prerequisite — create a config file: the server looks for its config at ~/.config/peerbridge/config.yaml by default. Create it from examples/config.example.yaml before starting Claude Desktop/Code:
mkdir -p ~/.config/peerbridge
cp examples/config.example.yaml ~/.config/peerbridge/config.yaml
# edit the file to match your paths
You can override the config path with the -config flag or the PEERBRIDGE_CONFIG environment variable.
macOS GUI apps and environment variables: because macOS does not pass shell environment variables to GUI apps like Claude Desktop or the Codex app, setting
PEERBRIDGE_CONFIG(orPATH) in your shell profile has no effect when the server is launched from a GUI. Place your config at the default path, and ifcodex/claudeare not found setagents.<name>.commandto an absolute path.
macOS/Linux: the bundled scripts/launch.sh launcher downloads the matching release binary on first run and verifies it against the release checksums.txt before executing it. No manual binary install needed.
Windows: the marketplace plugin's launcher is a POSIX shell script, so on Windows the plugin's MCP server will not start by itself (its skills still work). Use scripts\install.ps1 instead — see "Install on Windows" below — which registers peerbridge.exe directly in claude_desktop_config.json.
Trust note: the launcher downloads and runs a binary from GitHub Releases, checksum-verified against the release. Review the source at
scripts/launch.shandscripts/lib.shif you have concerns.
Install on Windows (Codex and/or Claude Desktop)
git clone https://github.com/jerryctt/peerbridge.git
cd peerbridge
powershell -ExecutionPolicy Bypass -File scripts\install.ps1 # Codex + Claude Desktop
powershell -ExecutionPolicy Bypass -File scripts\install.ps1 -Codex # or -Claude for one of them
# ... -Local .\peerbridge.exe to use a locally built binary; -NoClaudeConfigWrite to only print the JSON snippet
Works with Windows PowerShell 5.1 and PowerShell 7. It downloads and checksum-verifies the matching zip, installs peerbridge.exe to %LOCALAPPDATA%\peerbridge\, creates %APPDATA%\peerbridge\config.yaml from the example, writes the Codex [mcp_servers.peerbridge] block to %USERPROFILE%\.codex\config.toml and the skills to %USERPROFILE%\.agents\skills\, and merges mcpServers.peerbridge into %APPDATA%\Claude\claude_desktop_config.json (a .bak.peerbridge copy is kept). Edit allowed_roots (Windows paths such as C:/Users/you/code are fine), then restart the apps.
Windows notes: codex and claude are usually .cmd shims from npm — if the GUI app cannot find them, set agents.codex.command / agents.claude.command to the full path printed by (Get-Command claude).Source. On a timeout peerbridge kills the whole peer process tree with taskkill /T.
Install for Codex (CLI, macOS app, IDE extension)
git clone https://github.com/jerryctt/peerbridge.git
cd peerbridge
scripts/install-codex.sh # or: scripts/install-codex.sh --local ./peerbridge
This downloads and verifies the release binary (links it at ~/.local/bin/peerbridge), writes a [mcp_servers.peerbridge] block to ~/.codex/config.toml (with tool_timeout_sec = 120), installs the peer-review, peer-chat and peer-task skills into ~/.agents/skills/, and creates ~/.config/peerbridge/config.yaml if missing. Edit allowed_roots, then restart the Codex app (the CLI, the macOS app and the IDE extension share this configuration). In Codex, say "peer review my changes" or "ask claude what it thinks about this design".
Manual equivalent:
# ~/.codex/config.toml
[mcp_servers.peerbridge]
command = "/Users/you/.local/bin/peerbridge"
tool_timeout_sec = 120
startup_timeout_sec = 20
Configuration
The server resolves its config file in this order:
- The path given by the
-configflag, if provided. - The
PEERBRIDGE_CONFIGenvironment variable, if set. - The first of these that exists, otherwise the first one:
~/.config/peerbridge/config.yaml(all platforms), then the OS user config dir —%APPDATA%\peerbridge\config.yamlon Windows,~/Library/Application Support/peerbridge/config.yamlon macOS.
Recommended: place your config at ~/.config/peerbridge/config.yaml. GUI apps do not inherit shell environment variables, so PEERBRIDGE_CONFIG set in your shell profile will not be visible to a server launched from Claude Desktop or the Codex app.
Create a config file from the provided example — the paths in it are placeholders; change them to match your own setup:
mkdir -p ~/.config/peerbridge
cp examples/config.example.yaml ~/.config/peerbridge/config.yaml
# Absolute host paths that tools are allowed to access.
# The tool rejects any request that resolves outside these roots.
allowed_roots:
- /Users/yourname/code
# Maximum wall-clock time for a single job on the host (a review or one chat
# turn). Must include a unit (e.g. 600s, 10m). Jobs run in
# the background, so this can be much larger than the MCP client's per-call
# limit.
timeout: 600s
# Maximum bytes returned from a single tool invocation (output is truncated with a notice).
max_output_bytes: 200000
# How long job_status waits before answering "running". Longer = fewer polls =
# fewer permission prompts. Must stay below the client's per-call timeout
# (Codex tool_timeout_sec: 120 via our installers; Claude Desktop ~180s).
status_poll: 100s
# Tee peer CLI output to the server's stderr in real time (default: true).
# Claude Desktop captures this in ~/Library/Logs/Claude/mcp-server-peerbridge.log.
stream_output: true
# Peer agents. Both optional; defaults shown. Use absolute paths when the GUI
# app cannot find the CLI on its PATH (e.g. the output of `which claude`).
agents:
codex:
command: codex
extra_args: [] # e.g. ["--search"]
# model: gpt-5.5 # default when a call passes no model
# effort: medium # low | medium | high | xhigh | max
claude:
command: claude
extra_args: []
# model: opus
# effort: high
# Legacy, still honoured and appended to agents.codex.extra_args:
# codex_extra_args: ["-c", "model=o3"]
# task_start: let a peer edit files in a separate git worktree. Off by default.
# tasks:
# enabled: true
# timeout: 30m # per task turn
# max_running: 2 # concurrently running tasks
# Where task worktrees, patches and the task index live.
# Default: $XDG_STATE_HOME/peerbridge, else ~/.local/state/peerbridge
# state_dir: /Users/yourname/.local/state/peerbridge
Note: the config file is read once at server startup. After editing
config.yaml, fully restart Claude Desktop or the Codex app (they respawn the server) for changes to take effect. The effective values are logged at startup (look for theconfig loadedline — it shows the config path, timeout and agent commands actually in use).
Register with Claude Desktop
Add the following to your Claude Desktop config (usually ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"peerbridge": {
"command": "/usr/local/bin/peerbridge",
"args": ["-config", "/Users/yourname/.config/peerbridge/config.yaml"]
}
}
}
Replace /usr/local/bin/peerbridge with the actual path to the binary (e.g. ~/go/bin/peerbridge), and update the config path accordingly. The file examples/claude_desktop_config.example.json in this repo shows the same snippet.
Restart Claude Desktop after editing the config. You should see peerbridge appear in the MCP servers list.
Available Tools
| Tool | Purpose |
|---|---|
review_start(folder, agent?, scope?, base?, commit?, prompt?) |
Start a read-only review by a peer agent; returns job_id. |
chat_start(folder, message, agent?, model?, effort?, conversation_id?) |
Send one message to the peer; returns job_id. Pass the conversation_id from an earlier result to continue that conversation. |
task_start(folder, message, agent?, model?, effort?, conversation_id?, base?) |
Opt-in. The peer implements a change in a separate git worktree; returns job_id. |
job_status(job_id) |
Long-poll (≤50s) for a job's result. |
codex_review_start, codex_review_status |
Deprecated aliases of review_start(agent=codex) / job_status. |
All folder parameters are absolute HOST paths (e.g. /Users/you/proj), never /sessions/… sandbox paths.
review_start
| Parameter | Type | Required | Description |
|---|---|---|---|
folder |
string | yes | Absolute host path to the git repo |
agent |
string | no | codex or claude. Omit to use the other vendor automatically (Claude client → codex, Codex client → claude) |
scope |
string | no | uncommitted (default — staged+unstaged+untracked), base (against a base branch), or commit (a specific commit) |
base |
string | no | Base branch or ref; required when scope=base (e.g. main) |
commit |
string | no | Commit SHA; required when scope=commit |
prompt |
string | no | Custom review instructions (e.g. "focus on error handling"). Only for an explicitly focused review. Safe with any scope. |
model |
string | no | Peer model (see Model and effort) |
effort |
string | no | low, medium, high, xhigh or max (see Model and effort) |
agent=codex runs codex exec review --json (native: codex computes the diff itself) in a read-only sandbox without your codex config. agent=claude runs claude -p with a review prompt; peerbridge computes the diff with hardened read-only git and passes it on stdin. The finished result includes a conversation_id for follow-ups (chat_start / task_start); each review_start itself always starts a fresh review.
Returns:
Review started in the background.
job_id: 3fa4c19e02d1
agent: codex
mode: uncommitted
folder: /Users/you/proj
chat_start
| Parameter | Type | Required | Description |
|---|---|---|---|
folder |
string | yes | Absolute host path the peer may read |
message |
string | yes | What to say. Include the context the peer needs — it only sees the repo and this conversation. |
agent |
string | no | codex or claude; omit for automatic peer selection |
conversation_id |
string | no | conversation_id from an earlier job_status result (chat, review or task), to continue that conversation |
session_id |
string | no | Deprecated alias of conversation_id. Claude Desktop/Cowork strips an argument with this name, so use conversation_id |
model |
string | no | Peer model for this turn |
effort |
string | no | Reasoning effort for this turn: low, medium, high, xhigh or max |
Model and effort
model and effort pick the peer's model and reasoning depth for one call, e.g. review_start(folder=…, agent="claude", model="opus", effort="high").
- claude gets
--model <model> --effort <effort>;modelis an alias (opus,sonnet, …) or a full model id. - codex gets
-c model="<model>"(plus-c review_model="<model>"for reviews) and-c model_reasoning_effort="<effort>". - Precedence: the call's value, else
agents.<name>.model/.effortinconfig.yaml, else the CLI's own default. Each call resolves afresh; when continuing a chat, an omitted value is not re-sent and the CLI decides what to use. - Which efforts a model supports is up to the vendor CLI; an unsupported combination fails with the CLI's own error.
- If
extra_argsalready sets a model or effort (e.g.["-m", "o3"]), passing one too is rejected rather than guessing which flag wins: move it tomodel:/effort:in config.
peerbridge MCP questions
What tools does peerbridge MCP provide?
It exposes 14 tools, including folder, agent, scope, base, commit.
Can peerbridge run arbitrary commands?
No, peerbridge no longer runs arbitrary allowlisted commands; it only starts the peer CLIs with server-fixed, read-only arguments.
Is the code review process destructive to my current work?
By default, reviews are read-only. You can optionally enable a task mode where the peer implements changes in a separate git worktree that never touches your checkout.
How does peerbridge handle long-running reviews?
Reviews run as background jobs because they outlast MCP per-call timeouts, using start and status calls to manage the process.
What are the security measures for peer agents?
The server uses root-directory containment, symlink-resolved path checks, fixed read-only arguments, and prevents shell execution.