peer-agents-mcp
It is an MCP server that lets AI coding agents delegate code review, planning, debugging, verification, Q&A, and multi-turn collaboration to the Grok and Antigravity CLIs as peer reviewers.
Review diffs/patches with
peer_review_diff(sync or async)Create implementation plans with
peer_planDiagnose failures from logs/stack traces with
peer_debugVerify test/build output with
peer_verifyAsk general or grounded questions via
peer_ask(routes to Antigravity)Compare Plan A vs Plan B independently with
peer_debateContinue multi-turn sessions with
peer_turnandpeer_turn_asyncRun long-lived background jobs (
peer_implement_async,peer_review_diff_async,peer_debug_async) and poll/cancel/GC them withpeer_job_status,peer_job_cancel,peer_jobs_gcGet side-by-side low-level comparisons from both CLIs with
peer_compareManage sessions via
peer_summarize,peer_transcript,peer_list_sessions,peer_resetCheck CLI health with
peer_health
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@peer-agents-mcp review this diff for my PR"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
peer-agents-mcp
MCP server that lets other AI coding tools (Codex, Claude, Cursor, etc.) call the Grok CLI and Antigravity CLI as peer reviewers and collaborators.
What it does
This server wraps the local grok and agy (Antigravity) CLIs behind a clean Model Context Protocol (MCP) interface.
Any MCP-capable agent can now:
Send code changes, plans, errors, or questions to Grok or Antigravity
Receive structured peer feedback
Run multi-turn review/debug/planning sessions with session memory
Get independent opinions by running both CLIs on the same task
The primary agent (Codex, Claude, etc.) stays in control. It simply delegates specific tasks to these peers when it wants a second (or different) opinion.
Related MCP server: xAI Grok MCP Bridge
Core idea
Instead of one model doing everything, your main coding agent can use Grok and Antigravity as peers:
Grok for most coding work (reviews, planning, debugging, implementation critique)
Antigravity for large context, general knowledge, or multimodal tasks
Smart routing happens automatically based on the type of request.
Available tools
Tool | Purpose | Routed to |
| Review a unified diff or patch | Grok (usually) |
| Create an implementation plan | Grok |
| Diagnose failures from logs/stack traces | Grok |
| Check test/build output for safety | Grok |
| General grounded Q&A | Antigravity |
| Independently compare Plan A vs Plan B | Grok |
| Continue a multi-turn peer session | Same peer |
| Long-running follow-up turn (background job) | Same peer |
| Cold-start Grok implementation handoff (job) | Grok |
| Long-running diff review (background job) | Grok |
| Long-running debug handoff (background job) | Grok |
| Poll a background job (includes | — |
| Cancel a background job | — |
| Garbage-collect old terminal jobs | — |
| Low-level side-by-side call to both CLIs | Both |
Additional session tools: peer_summarize, peer_transcript, peer_list_sessions, peer_reset, and peer_health.
All routed tools accept full file contents via the files parameter and diffs via diff. Never send summaries — send the actual content.
When to use sync vs async
Grok sync reviews of ordinary diffs typically take 3–6 minutes. The Grok child timeout is GROK_TURN_TIMEOUT_MS (default 6 minutes). Raising the child timeout does not raise the host MCP client wait. If the host gives up first, Codex never sees durationAdvisory / continuationHint / nativeSessionId in that tool response — use *_async.
The server does not silently convert sync tools into jobs.
Use sync ( | Use async ( |
Ordinary diffs / plans that fit in ~80k prompt chars | ≥ ~80k chars (~20k tokens), near the 120k cap, or truncated |
Default / medium risk |
|
Follow-up “re-check this one file” | Implementation handoff ( |
Host can wait ~6 minutes | Host MCP timeout ≤ 2–3 minutes; huge logs; multi-attempt debug |
Sync Grok/routed results may include additive durationAdvisory when the prompt was truncated, estimated tokens exceed ~20k (~80k chars), risk_level=high / focus=security, or a stub auto-continue was consumed. Example:
{
"durationAdvisory": "Grok sync reviews of this size often take 3–6 minutes. If your MCP client times out sooner, use peer_review_diff_async / peer_turn_async and poll peer_job_status."
}A truncated peer_review_diff still runs synchronously (tools-against-cwd instruction is prepended). Prefer peer_review_diff_async next time; do not treat truncation as a hard reject.
Long-running async jobs
Large implementation handoffs can exceed the MCP client's synchronous tool timeout. Use the async path instead of blocking on peer_turn:
Start work with
peer_implement_async(cold start) orpeer_turn_async(existing session).Continue local work while the peer runs.
Poll
peer_job_statusevery 30–60 seconds (avoid aggressive polling).While
statusisrunning, optionalprogressmay includetextSnippet,lastThought, andeventCount(Grokstreaming-json/ agystream-json).When
statusissucceeded, readresultand continue withpeer_turnif needed.Use
peer_job_cancelto stop a queued/running job owned by this MCP process.
Terminal statuses: succeeded, failed, timed_out, cancelled, orphaned.
Idempotency: retries with the same idempotency_key return the same job (running or sticky terminal). After timed_out / cancelled / failed, use a new key to retry the work.
Jobs and completed results are stored under ~/.peer-agents/jobs/. Live provider processes do not survive MCP server restarts; non-terminal jobs are marked orphaned on hydrate (unless the session already committed the operation, which recovers as succeeded).
Terminal jobs older than 7 days are garbage-collected on hydrate (override with PEER_AGENTS_JOB_GC_MAX_AGE_MS) or via peer_jobs_gc.
Async jobs use a separate timeout from synchronous turns:
PEER_AGENTS_JOB_TIMEOUT_MS— default 30 minutes (1800000)GROK_JOB_TIMEOUT_MS/ANTIGRAVITY_JOB_TIMEOUT_MS— optional per-provider overridesPEER_AGENTS_JOB_GC_MAX_AGE_MS— terminal job retention (default 7 days)PEER_AGENTS_GROK_TRANSPORT—headless(default) oracpfor warm process poolPEER_AGENTS_GROK_ACP_MAX_CLIENTS— max concurrent ACP processes (default 4)PEER_AGENTS_GROK_ACP_IDLE_MS— ACP between-turns idle recycle (defaultmax(5 min, GROK_TURN_TIMEOUT_MS + 60s)). Idle is not the job lifetime; in-flightsession/promptignores it.
Keep the MCP server process alive for the duration of a job.
Grok transport: headless vs ACP
|
| |
Invocation |
| Long-lived |
Latency | Cold start every turn | Warm process; multi-turn reuses process + session |
CLI features | Sandbox, worktree, minted | Subset ( |
Enable | (default) |
|
Prefer headless for one-shot reviews with strict sandboxing. Prefer acp when you run many follow-up peer_turns and want lower process-startup cost.
How other agents use it
Codex, Claude, or any other MCP client connects to this server over stdio. Once connected, the agent can call the peer tools exactly like any other tool.
Typical flow:
Your agent prepares a diff, error log, or task description.
It calls
peer_review_diff,peer_plan,peer_debug, etc.The server invokes the appropriate CLI(s) in headless mode.
The peer response comes back with a
sessionId.Your agent can follow up later with
peer_turnusing thatsessionId.
This gives you persistent, contextual peer conversations without the primary agent having to manage CLI invocation itself.
Prerequisites
Node.js ≥ 18
The
grokCLI (or setGROK_COMMAND)The
agyCLI (Antigravity, or setANTIGRAVITY_COMMAND)
Both CLIs must be authenticated and working on your machine.
Installation & usage
git clone https://github.com/Rakeen70210/peer-agents-mcp
cd peer-agents-mcp
npm install
npm run buildRun directly:
node dist/index.jsMCP client configuration
Add it to your client's MCP servers config (example for a typical stdio setup):
{
"mcpServers": {
"peer-agents": {
"command": "node",
"args": ["/absolute/path/to/peer-agents-mcp/dist/index.js"],
"env": {
"GROK_COMMAND": "/home/you/.grok/bin/grok",
"ANTIGRAVITY_COMMAND": "/home/you/.local/bin/agy"
}
}
}
}Environment variables
GROK_COMMAND— path to grok binary (default:grok)ANTIGRAVITY_COMMAND— path to agy binary (default:agy)GROK_ARGS/ANTIGRAVITY_ARGS— JSON array of extra CLI argsANTIGRAVITY_CONVERSATIONS_DIR— override agy conversation store used as fallback session-id capture (default:~/.gemini/antigravity-cli/conversations)PEER_AGENTS_WORKTREE_DIR— parent directory for DIY Grok git worktrees (default:~/.peer-agents/worktrees)PEER_AGENTS_STORAGE_DIR— where sessions are persisted (default:~/.peer-agents/sessions)PEER_AGENTS_ENABLED_PROVIDERS— comma list whitelist of peer CLIs (grok,antigravity). Useantigravityalone when the host is Grok so peers never re-enter Grok.PEER_AGENTS_DISABLED_PROVIDERS— comma list blacklist (ignored ifPEER_AGENTS_ENABLED_PROVIDERSis set)GROK_TURN_TIMEOUT_MS— Grok sync timeout for headless and ACP (default 6 minutes /360000). Only source besides per-calltimeoutMs. Grok does not readPEER_AGENTS_TURN_TIMEOUT_MS.PEER_AGENTS_TURN_TIMEOUT_MS— Antigravity sync fallback only (default 300s). Does not pin Grok. Unset it or setGROK_TURN_TIMEOUT_MSexplicitly. Operators who want the old 120s Grok timeout must setGROK_TURN_TIMEOUT_MS=120000.ANTIGRAVITY_TURN_TIMEOUT_MS— optional Antigravity sync override (default 300s)PEER_AGENTS_GROK_ACP_IDLE_MS— ACP between-turns idle recycle (defaultmax(5 min, GROK_TURN_TIMEOUT_MS + 60s)). In-flightsession/promptignores idle (promptDepth). Not the 30-minute job lifetime.PEER_AGENTS_JOB_TIMEOUT_MS— async job timeout (default 30 minutes)GROK_JOB_TIMEOUT_MS/ANTIGRAVITY_JOB_TIMEOUT_MS— optional async per-provider overridesPEER_AGENTS_MAX_PROMPT_CHARS— safety limit on prompt size (default 120000); truncation prepends a tools-against-cwd instruction and continues the sync turn
Multi-turn peer sessions
Each routed call returns a sessionId. Use peer_turn to continue the conversation:
Tell the peer what changed
Attach new diffs or files
Ask it to re-review or check your fixes
Sessions are persisted to disk, so they survive across restarts of the MCP server.
Grok and Antigravity multi-turn turns prefer native CLI resume when a conversation/session id was captured on the first turn; otherwise the MCP rehydrates recent transcript into the prompt.
Grok CLI integration (1.0.x+)
Grok peer turns use modern headless flags under the hood (callers do not pass these):
Concern | Behavior |
Large prompts | Always |
Multi-turn |
|
Reviewer / critic |
|
Planner |
|
Implementer |
|
Permissions | Reviewer/critic/planner use |
| Default git worktree isolation via |
Review findings | Best-effort parse of findings JSON from final text; prose is a valid review. Grok headless does not pass |
Risk / security | Elevated |
Specialists | Packaged |
Sync + async output | Always |
ACP pool (opt-in) |
|
Spend telemetry |
|
Antigravity CLI integration (agy 1.1.8+)
Antigravity peer turns use print mode under the hood (callers do not pass these flags):
Concern | Behavior |
Invocation |
|
Multi-turn |
|
Review findings |
|
Reviewer / critic |
|
Planner |
|
Implementer |
|
Risk |
|
Workspace |
|
Agent | Optional |
Slash/skills | Always |
Async progress |
|
Health | Prefer |
Spend telemetry |
|
agy still has no worktree, --prompt-file, or ACP transport. Sync turns stay --output-format json; only background jobs stream.
Design notes
The server never modifies your repo itself — it only runs the CLIs you already have.
User messages in session transcripts are labeled from the caller's perspective (commonly "Codex").
Idempotency keys are supported so repeated calls with the same key are safe.
Context quality hints are returned when the input looks too thin (missing files, diffs, etc.).
Implementation handoffs default to an isolated git worktree (
--cwdinto it) so the peer does not clobber a dirty main tree.
License
MIT (or as specified in the repo).
Available Tools
13 toolspeer_askC
Before calling: read relevant source files and attach full contents via files. Pass complete diffs/logs — never prose summaries. Set task with goals, affected behavior, and specific concerns. General knowledge or grounded Q&A — routes to Antigravity.
Inputs: question (required), repo_path (required), idempotency_key (required), context, +2 more.
peer_compareA
Before calling: read relevant source files and attach full contents via files. Pass complete diffs/logs — never prose summaries. Set task with goals, affected behavior, and specific concerns. Low-level dual-CLI comparison (prefer phase tools for routing).
Inputs: message (required), repo_path (required), task (required), idempotency_key (required), +6 more.
peer_debateA
Before calling: read relevant source files and attach full contents via files. Pass complete diffs/logs — never prose summaries. Set task with goals, affected behavior, and specific concerns. Independently compare Plan A vs Plan B without cross-contamination.
Inputs: task (required), plan_a (required), plan_b (required), repo_path (required), +2 more.
peer_debugA
Before calling: read relevant source files and attach full contents via files. Pass complete diffs/logs — never prose summaries. Set task with goals, affected behavior, and specific concerns. Route a debugging request after failures.
Inputs: error_log (required), repo_path (required), idempotency_key (required), attempted_fixes, +4 more.
peer_healthA
Check whether Grok and Antigravity CLIs are responsive
Inputs: no named parameters.
peer_list_sessionsB
List persisted peer sessions, optionally filtered by repo path
Inputs: repo_path.
peer_planA
Before calling: read relevant source files and attach full contents via files. Pass complete diffs/logs — never prose summaries. Set task with goals, affected behavior, and specific concerns. Route an implementation planning request to the best peer model(s).
Inputs: task (required), repo_path (required), idempotency_key (required), constraints, +4 more.
peer_resetC
Clear a session transcript or delete the session entirely
Inputs: session_id (required), idempotency_key (required), expected_version, keep_metadata.
peer_review_diffB
Before calling: read relevant source files and attach full contents via files. Pass complete diffs/logs — never prose summaries. Set task with goals, affected behavior, and specific concerns. Route a diff review to the best peer model(s) based on focus and risk.
Inputs: diff (required), repo_path (required), idempotency_key (required), focus, +4 more.
peer_summarizeC
Return the rolling session summary and unresolved issues
Inputs: session_id (required).
peer_transcriptC
Export recent transcript turns
Inputs: session_id (required), max_turns, format.
peer_turnC
Before calling: read relevant source files and attach full contents via files. Pass complete diffs/logs — never prose summaries. Set task with goals, affected behavior, and specific concerns. Follow up in an existing routed peer session (use session_id from a prior result).
Inputs: session_id (required), message (required), idempotency_key (required), diff, +2 more.
peer_verifyB
Before calling: read relevant source files and attach full contents via files. Pass complete diffs/logs — never prose summaries. Set task with goals, affected behavior, and specific concerns. Route verification of tests/build output.
Inputs: test_output (required), repo_path (required), idempotency_key (required), diff, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
While each tool has a distinct purpose, the descriptions share extensive boilerplate text (e.g., 'Before calling: read relevant source files...'), making it harder for an agent to quickly differentiate between tools like peer_ask, peer_compare, and peer_debate. The specific routing information at the end helps but requires careful reading.
All tools follow the snakename pattern with the consistent prefix 'peer', using varied but appropriate verbs/verb phrases. No mixing of conventions like camelCase or different prefixes.
13 tools is well within the ideal 3-15 range for a server focused on peer agent interactions. Each tool covers a distinct operation without unnecessary bloat or missing essentials.
The tool set covers a broad range of peer agent workflows: asking, comparing, debating, debugging, planning, reviewing, verifying, and session management. Minor gaps like explicit session creation are implicitly handled via peer_turn, so no critical missing operations.
Maintenance
Related MCP Connectors
Source-checked CLI guides and model-aware planning for Claude Code, Codex, and Grok Build.
Multiplayer for the coding agents your team already uses: shared tasks, decisions, skills and tools.
AI colleagues that keep your standards, your project and their reasoning between sessions
Shared control plane for AI coding agents — tasks, memory, decisions, file locks. 12 tools.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables Claude Code to request independent code reviews and second opinions from other AI models (like Gemini, GPT-OSS) via the Antigravity CLI, directly from the chat.1MIT
- FlicenseAqualityBmaintenanceEnables using the xAI Grok CLI as an MCP sub-agent for code review, asking questions, and continuing conversations within MCP hosts like Claude Code.4-
- AlicenseNot gradedqualityDmaintenanceConnects OpenAI Codex and Claude Code to the local Grok Build CLI for second-opinion code reviews, bounded coding tasks, web research, media generation, and TTS.3Apache 2.0
- AlicenseAqualityDmaintenanceEnables Codex to delegate coding tasks to Grok Build CLI, with Codex handling planning and review while Grok executes.63MIT