code-review-annotator

code-review-annotator

Tool-call review for Claude Code. Every Edit / Write / MultiEdit / NotebookEdit Claude Code runs is captured as a before→after snapshot, rendered in a browser UI as a timeline of cards. Leave inline comments on specific lines of either side, then let Claude Code read them via MCP and apply fixes.

Beyond the tool-call timeline, you can also create ad-hoc git diff review sessions (compare any two refs — branch / HEAD / SHA / INDEX / WORKTREE) and browse sessions (annotate any file in the worktree, no diff). Comments made in each mode are kept independent of one another.

Comments support four scopes: line (a specific line range), file (a whole file), multi-file (cross-cutting change across N files), and view (review-level / architectural note).

ssh -L 8080:localhost:8080 your-server
npx code-review-annotator --port 8080

One HTTP server can serve multiple projects / worktrees. The plugin's MCP server self-registers into a central registry; the browser UI lists every registered project in a dropdown.

---

Why

When Claude Code is making changes on a remote machine, you want to see each edit it made individually — not squashed into a single git diff — so you can comment on decisions at the moment they happen. This tool closes that loop:

1. Claude Code runs Edit / Write / MultiEdit / NotebookEdit — Pre/PostToolUse hooks capture the before and after snapshot
2. You SSH port-forward and review the timeline of tool calls in a browser UI
3. You click a card to see its before→after diff, click lines to leave inline comments
4. You tell Claude Code "fix review comments" — it reads comments via MCP, applies fixes, and replies on each thread
5. Resolve or push back in the browser, then iterate

There is no base branch, no merge-base. Each tool call is a standalone, frozen snapshot.

---

Installation

As a Claude Code Plugin (recommended)

The plugin ships .mcp.json and hooks/hooks.json, so install via Claude Code's plugin commands:

/plugin marketplace add /path/to/code-review-annotator
/plugin install code-review-annotator@code-review-annotator-local

The plugin bundles:

• An MCP server that auto-connects — no claude mcp add needed
• Pre/PostToolUse hooks that capture every Edit / Write / MultiEdit / NotebookEdit Claude Code runs

Standalone (npx)

# HTTP server (multi-project — projects register via the plugin's MCP)
npx code-review-annotator --port 8080

# Or pre-seed the registry with a specific project at startup
npx code-review-annotator --dir /path/to/project --port 8080

# MCP server (for projects that aren't using the plugin)
claude mcp add code-review -- npx code-review-annotator --mcp

Note: standalone MCP mode alone does not capture tool calls — you also need the plugin's Pre/PostToolUse hooks (or equivalent hooks wired manually into .claude/settings.json) for snapshots to appear in the UI.

---

Usage

1. Start the HTTP server on the remote

npx code-review-annotator --port 8080

Flag	Default	Description
--port	8080	HTTP server port
--dir	—	Optional in HTTP mode: if set, auto-registers this project at startup.
--mcp	—	Run as MCP stdio server instead

Projects register themselves into $XDG_CONFIG_HOME/code-review-annotator/projects.json (default ~/.config/...). The HTTP server also writes its current port into every registered project on startup, so the plugin's hook script knows where to POST snapshots. Stale entries (dir no longer exists) are filtered out of the UI automatically. The registry is safe to hand-edit.

2. Open the UI locally

ssh -L 8080:localhost:8080 your-server
open http://localhost:8080

3. Review and annotate

The header has a three-way mode switcher:

• Tool calls — the default live timeline. Each captured Edit / Write / MultiEdit / NotebookEdit is a card. Click one to open its before→after diff. Newest at top. Status badges: pending / orphan.
• Git diff — user-created sessions that compare any two refs. Pick from branches / commits / HEAD / INDEX (staged) / WORKTREE (current files incl. untracked), or paste a SHA. A warning appears if the two refs have no ancestor relationship — that case is outside this tool's design but still renders A..B. Each session is saved; switch between sessions via the sidebar dropdown.
• Browse — a user-created session that lists every worktree file (tracked + untracked, respecting .gitignore). No diff; pick a file, leave comments on any line.