ReviewSwarm

Collaborative AI Code Review via MCP
Multiple specialized AI agents review your code simultaneously,
coordinate through a shared whiteboard, and reach consensus on findings.

How It Works

ReviewSwarm is a review-only tool. It finds bugs, it does not fix them.

 You: "Review src/"
 ─────────────────►  ReviewSwarm Server
                     ┌────────────────────────┐
                     │  Phase 1: REVIEW        │
                     │  claim files             │
                     │  post findings           │
                     │  mark_phase_done         │
                     ├──────────────────────────┤
                     │  ═══════ BARRIER ═══════ │
                     ├──────────────────────────┤
                     │  Phase 2: CROSS-CHECK    │
                     │  get_findings             │
                     │  react (confirm/dispute)  │
                     │  mark_phase_done         │
                     ├──────────────────────────┤
                     │  ═══════ BARRIER ═══════ │
                     ├──────────────────────────┤
                     │  Phase 3: REPORT          │
                     │  end_session              │
                     │  auto-save reports        │
                     └────────────┬─────────────┘
                                  │
                                  ▼
                     report.md / report.json / report.sarif
                     (recommendation report — no code changes)

Step by step

# 1. REVIEW: one command launches everything
review-swarm review . --scope src/ --task "security audit"

# Orchestrator: creates session, picks experts, assigns files, returns plan.
# Agents execute the plan:
#   Phase 1 — each expert reviews files, posts findings
#   ═══ BARRIER ═══ (all agents must finish before Phase 2)
#   Phase 2 — each expert reads others' findings, confirms/disputes
#   ═══ BARRIER ═══
#   Phase 3 — end_session auto-saves reports

# 2. REPORTS: auto-saved to session directory
ls ~/.review-swarm/sessions/sess-2026-03-22-001/
#   report.md      ← Markdown (executive summary, per-file, per-expert)
#   report.json    ← JSON (machine-readable)
#   report.sarif   ← SARIF 2.1.0 (GitHub Code Scanning)

# That's it. ReviewSwarm's job is done.
# The report is a spec — each finding has file, lines, evidence, and suggestion.
# What you do with it (manual fix, AI fix-agent, ignore) is up to you.

Fix tracking (optional)

If you use a separate tool/agent to fix bugs from the report, you can track progress via ReviewSwarm:

# After fixing a bug, mark the finding as fixed:
mark_fixed(session_id, "f-a1b2c3", fix_ref="commit:abc1234")

# Or batch-update after fixing multiple bugs:
bulk_update_status(session_id, ["f-a1b2c3", "f-d4e5f6"], "fixed", reason="PR #42")

This is status tracking, not code modification. ReviewSwarm never changes your code.

Key principles

• Review agents are read-only — they produce a recommendation report, never modify code
• Phase barriers — Phase 2 cannot start until all agents finish Phase 1
• Consensus — 2+ confirms = confirmed, 1+ dispute = disputed
• Reports as specs — each finding is a self-contained bug spec with file, lines, evidence, and suggestion
• Fix tracking is optional — mark_fixed / bulk_update_status track what was fixed, but fixing is external

One Command Review

review-swarm review . --scope src/ --task "security audit"

Or via MCP:

orchestrate_review(project_path=".", scope="src/", task="security audit")

ReviewSwarm creates a session, selects experts, assigns files, and returns a 3-phase execution plan with barrier synchronization.

Task keywords (EN/RU): security, performance, concurrency, quality, pre-release, bug, type, log, dependency, test, doc — the orchestrator auto-selects relevant experts.

What is ReviewSwarm?

ReviewSwarm is not an LLM and not a fixer — it's review infrastructure. It provides 26 MCP tools that AI agents use to:

• Post findings with structured evidence (actual + expected + source_ref)
• Claim files for review (advisory locks with TTL)
• React to each other's work (confirm, dispute, extend, duplicate)
• Message each other — direct, broadcast, query/response (star topology)
• Reach consensus automatically (2+ confirms = confirmed)
• Generate reports in Markdown, JSON, or SARIF

ReviewSwarm produces a recommendation report. It never modifies your code. What you do with the report is up to you.

Install

uv tool install review-swarm

Upgrade:

uv tool upgrade review-swarm

Need uv? See uv installation. For the full swarm suite (ReviewSwarm + ArchSwarm + DocSwarm + FixSwarm + SpecSwarm + SwarmKB), see INSTALL.md.

From source (development):

git clone https://github.com/fozzfut/review-swarm.git
cd review-swarm && pip install -e ".[dev]"

IDE Setup

Claude Code (recommended)

One command:

claude mcp add review-swarm -- review-swarm serve --transport stdio

Or add manually to ~/.claude/settings.json or project .mcp.json:

{
  "mcpServers": {
    "review-swarm": {
      "command": "review-swarm",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

Cursor / Windsurf / Cline (SSE)

Start server first: review-swarm serve --port 8787

{
  "mcpServers": {
    "review-swarm": {
      "url": "http://127.0.0.1:8787/sse"
    }
  }
}

CLI

# Orchestrator (one-command review)
review-swarm review . --scope src/ --task "security audit"
review-swarm review . --task "pre-release" --experts 5

# Server
review-swarm serve --transport stdio
review-swarm serve --port 8787

# Session management
review-swarm init
review-swarm list-sessions
review-swarm report <session-id>
review-swarm report <session-id> --format json

# Monitoring & analysis
review-swarm tail <session-id>                           # Live event stream
review-swarm stats                                       # Aggregate stats
review-swarm stats <session-id>                          # Session breakdown
review-swarm diff <session-a> <session-b>                # Compare reviews
review-swarm export <session-id> --format sarif -o out.sarif

# Expert profiles
review-swarm prompt --list
review-swarm prompt <expert-name>

# Maintenance
review-swarm purge --older-than 30

MCP Tools (26)

Orchestrator

Session Management

Expert Coordination

Findings

Fix Tracking

Phase Barriers (Two-Pass Sync)

Real-Time Events

Agent Messaging (Star Topology)

Every tool response includes _pending — unread messages piggyback on every call so agents react immediately.

Two-Pass Review with Phase Barriers

Agents can't start cross-checking until everyone finishes reviewing:

Phase 1: REVIEW
  Expert A reviews → mark_phase_done(sid, "threading-safety", 1)
  Expert B reviews → mark_phase_done(sid, "api-signatures", 1)
  Expert C reviews → mark_phase_done(sid, "consistency", 1)
                     ════════════ BARRIER ════════════
                     check_phase_ready(sid, 2) → ready: true

Phase 2: CROSS-CHECK
  Expert A reads findings, reacts → mark_phase_done(sid, "threading-safety", 2)
  Expert B reads findings, reacts → mark_phase_done(sid, "api-signatures", 2)
  Expert C reads findings, reacts → mark_phase_done(sid, "consistency", 2)
                     ════════════ BARRIER ════════════
                     check_phase_ready(sid, 3) → ready: true

Phase 3: REPORT
  end_session → auto-saves report.md + report.json + report.sarif

Fix Tracking (Optional)

ReviewSwarm does not fix code. These tools are for tracking what was fixed externally:

# After you (or your fix-agent) fix a bug, mark it in ReviewSwarm:
mark_fixed(session_id, "f-a1b2c3", fix_ref="commit:abc1234")

# Or batch-update:
bulk_update_status(session_id, ["f-a1b2c3", "f-d4e5f6"], "fixed",
                   reason="Fixed in PR #42")

Finding statuses: open → confirmed → fixed / wontfix / disputed

13 Expert Profiles

All language-agnostic: Python, JS/TS, Go, Rust, Java, Kotlin, C#, C/C++, Ruby, Elixir, Swift, PHP.

Consensus Algorithm

1+ duplicate  →  DUPLICATE
1+ dispute    →  DISPUTED
N+ confirm    →  CONFIRMED  (N = confirm_threshold, default 2)
otherwise     →  OPEN

Agent Communication (Star Topology)

     threading-safety
            ↕
api-signs ↔ Hub ↔ consistency
            ↕
     security-surface

Message types: direct, broadcast, query (always urgent), response

Piggyback _pending: every tool response includes unread message count + preview. Agents react immediately — no polling loop, no race conditions.

Safety

Configuration

~/.review-swarm/config.yaml:

storage_dir: "~/.review-swarm"
max_sessions: 50
default_format: "markdown"
session_timeout_hours: 24

consensus:
  confirm_threshold: 2
  auto_close_duplicates: true

experts:
  custom_dir: "~/.review-swarm/custom-experts"
  auto_suggest: true

rate_limit:
  max_findings_per_minute: 60
  max_messages_per_minute: 120

Data Storage

~/.review-swarm/sessions/sess-2026-03-22-001/
  ├── meta.json          # Session metadata + report paths
  ├── findings.jsonl     # Findings (one per line)
  ├── claims.json        # File claims
  ├── reactions.jsonl    # Reactions log
  ├── events.jsonl       # Real-time events
  ├── messages.jsonl     # Agent-to-agent messages
  ├── phases.json        # Phase barrier state
  ├── report.md          # Auto-saved Markdown report
  ├── report.json        # Auto-saved JSON report
  └── report.sarif       # Auto-saved SARIF report

Architecture

src/review_swarm/
├── orchestrator.py        # One-command review planning
├── server.py              # 26 MCP tools + resources + subscriptions
├── models.py              # Finding, Claim, Reaction, Event, Message
├── session_manager.py     # Session lifecycle, caching, auto-expiry
├── finding_store.py       # JSONL storage + in-memory index (atomic writes)
├── claim_registry.py      # Advisory file claims with TTL (atomic writes)
├── reaction_engine.py     # Consensus engine + duplicate reaction guard
├── report_generator.py    # Markdown, JSON, SARIF reports
├── event_bus.py           # Real-time event pub/sub (thread-safe)
├── message_bus.py         # Agent messaging, star topology (thread-safe)
├── phase_barrier.py       # Two-pass sync barriers
├── rate_limiter.py        # Per-agent sliding window rate limiter
├── expert_profiler.py     # Profile loading + auto-suggestion
├── logging_config.py      # Structured logging
├── config.py              # Config with validation
├── cli.py                 # Click CLI (review, tail, stats, diff, export...)
└── experts/               # 13 YAML expert profiles

Development

pip install -e ".[dev]"
pytest                    # 227 tests, ~3s
mypy src/review_swarm/

CI: Python 3.10/3.11/3.12 on Ubuntu + Windows.

License

MIT © 2026 Ilya Sidorov