Batch Review

Batch Review

A collaborative code and markdown review tool that bridges human reviewers and AI agents. Both can browse files, inspect git diffs, leave structured comments, and save a final review report — all from the same UI, in real time.

---

Features

GitHub-style math example

The preview uses the delimiter rules from Writing mathematical expressions: inline $…$, GitHub’s dollar-backtick inline form (rewritten to $…$ before parsing), display $$…$$, and fenced math code blocks. Rendering is KaTeX rather than GitHub’s MathJax, so a few uncommon macros can differ even when markdown syntax matches.

This app does not embed raw HTML in the markdown preview, so GitHub’s $ workaround for literal dollar signs in prose is unavailable here—inside math, escape $ as \$ per GitHub’s docs.

Examples:

Inline: $\sqrt{3x-1}+(1+x)^2$

Dollar-backtick (GitHub-compatible): $e^{i\pi} + 1 = 0$

$$ \nabla_\theta J(\theta) = \mathbb{E}_{(s, a) \sim \pi_\theta} \left[\nabla_\theta \log \pi_\theta(a \mid s)\, R(s, a)\right] $$

WaveDrom example

Fenced wavedrom ` blocks are parsed as WaveJSON (via JSON5, so unquoted/single-quoted keys are fine) and rendered inline, with the same source/rendered toolbar toggle as Mermaid. Three diagram kinds are supported, selected automatically from the JSON shape:

A digital timing diagram (signal):

{signal: [

{name: 'clk', wave: 'p.....'}, {name: 'data', wave: 'x.345x', data: ['head', 'body', 'tail']}, {name: 'req', wave: '0.1..0'}, {name: 'ack', wave: '1.....'} ]}

A bit-field / register diagram (reg):

{reg: [

{bits: 7, name: 'opcode'}, {bits: 5, name: 'rd'}, {bits: 3, name: 'funct3'}, {bits: 5, name: 'rs1'}, {bits: 12, name: 'imm[11:0]'} ], config: {bits: 32}}

A logic / schematic diagram (assign):

{assign: [["z", ["|", "a", ["&", "b", "c"]]]]}

---

Architecture

At runtime, Batch Review is a single Python application that serves the browser UI, exposes REST and WebSocket endpoints for that UI, and optionally exposes the same review session to MCP clients.

flowchart LR

CLI["CLI entry point uv run batch-review"] Browser["Browser UI React + Zustand"] McpHost["MCP host Cursor / Claude Desktop / VS Code / other clients"] AgentCli["Coding agent Claude Code / Cursor CLI / Codex batch-review "]

subgraph Backend["Batch Review backend process"] Server["FastAPI app static frontend / REST /api/* WebSocket /ws"] Mcp["FastMCP server stdio transport HTTP transport /mcp/"] State["Shared AppState repo root, comments, per-client MCP sessions, connected WebSocket clients"] end

Repo["Git repository under review"] Output["Saved review output review_comments.json review_comments.md"] PortFile[".batch_review/server.json discovery file"]

CLI --> Server CLI --> Mcp Server --> Browser Browser -->|"REST reads/writes"| Server Browser <-->|"live sync"| Server Server --> State Mcp --> State McpHost -->|"stdio or HTTP MCP"| Mcp AgentCli -->|"REST /api/*"| Server AgentCli -.->|"reads for discovery"| PortFile Server -.->|"writes on start"| PortFile State -->|"read files, diffs, existing review data"| Repo State -->|"save/load review reports"| Output State -.->|"broadcast UI events"| Browser

• The browser loads the React app from the FastAPI server, fetches files/comments/config over REST, and stays synchronized through /ws.
• MCP tools and REST routes both operate on the same in-memory AppState, so agent-created comments appear in the UI immediately. Every comment carries a userid; browser comments default to the Windows/Linux/macOS account running the server, while MCP connections and CLI profiles can change their own current userid.
• Multiple MCP clients can connect to one server concurrently. They share the collaborative comment collection, but each client gets an isolated application session and current userid; legacy FastMCP connections map their Context.session_id to that application session, while modern stateless clients pass its private ID explicitly.
• In --mcp mode, the HTTP server keeps the web UI available while FastMCP also runs over stdio for editor and CLI hosts.
• In CLI client mode, coding agents invoke batch-review (e.g. add-comment, diff) which calls the same REST endpoints — no MCP tool schemas loaded into agent context. The server writes .batch_review/server.json on startup so CLI verbs can discover it.

---

Distribution

• [PyPI — `batch-review-mcp`](https://pypi.org/project/batch-review-mcp/) — published wheels and sdist for pip / uv.
• [Official MCP Registry — `io.github.hevangel/batch-review-mcp`](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.hevangel%2Fbatch-review-mcp/versions/latest) — latest published server metadata (JSON API; the registry site is still preview).

---

Requirements

• Python ≥ 3.13 with uv
• Node.js ≥ 22 (for the one-time frontend build; matches GitHub Actions)

---

Installation

git clone https://github.com/hevangel/batch-review-mcp.git

cd batch-review-mcp uv sync

The first run will automatically build the React frontend if frontend/dist/ does not exist (requires Node.js + npm on PATH).

---

Usage

Standalone mode (browser opens by default)

# Review the current directory

uv run batch-review

Review a specific git repository

uv run batch-review --root /path/to/your/repo

Custom host / port

uv run batch-review --root /path/to/repo --host 0.0.0.0 --port 9100

Specify output filenames

uv run batch-review --root /path/to/repo --output review --output-dir /tmp/reviews

→ saves /tmp/reviews/review.json and /tmp/reviews/review.md

The server auto-selects a free port in the 9000–9999 range if the default port is already in use.

MCP stdio mode (Claude Desktop / Cursor / any MCP client; browser opens by default)

uv run batch-review --mcp --root /path/to/repo

The HTTP server starts in a background thread (so the browser UI remains accessible), your default browser opens to the app URL (same as standalone mode; use --no-browser to skip), and the MCP stdio transport runs in the main thread.

Claude Desktop config (claude_desktop_config.json):

{

"mcpServers": { "batch-review": { "command": "uv", "args": ["run", "batch-review", "--mcp", "--root", "/path/to/repo"] } } }

CLI client mode (token-efficient agent interface)

For coding agents (Claude Code, Cursor CLI, Codex, etc.), the CLI client mode is more token-efficient than loading 18 MCP tool schemas into context. Each verb is one process invocation that emits a single JSON document to stdout. The CLI talks to a running server over REST, so every comment and highlight also appears in the human reviewer's browser UI in real time.

# Start the server in the background (browser opens by default)

batch-review start --root .

{"web_url": "http://127.0.0.1:9000", "pid": 12345, "port": 9000}

List changed files

batch-review changes

[{"path": "main.py", "status": "M", ...}, ...]

Inspect a diff

batch-review diff main.py

Identity defaults to the OS account running the command; change it when needed

batch-review get-userid batch-review set-userid reviewer-a

Add a comment anchored to a line range (captures the current userid)

batch-review add-comment main.py 10 15 "This null check is redundant."

Save the review report (JSON + Markdown)

batch-review save

Stop the server when done

batch-review stop

Server discovery — verbs auto-discover a running server in priority order: the BATCH_REVIEW_WEB_URL env var, then /.batch_review/server.json (written by start), then probing ports 9000–9999.

CLI identity — get-userid and set-userid manage the userid attached to new CLI comments. The default is the local OS account from Python's cross-platform account lookup. Profiles are stored independently under .batch_review/users/; use --profile NAME or BATCH_REVIEW_USER_PROFILE when multiple agents share one checkout. BATCH_REVIEW_USERID or add-comment --userid ID overrides the selected profile for one process/request. Userids may contain printable international text (maximum 25