review-assist

<h1 align="center">Review Assist</h1>

<p align="center"> <strong>Review AI-written code as fast as agents write it.</strong><br> Turn a coding agent's session into a guided, verifiable pull-request review. </p>

<p align="center"> <a href="#install">Install</a> · <a href="#how-it-works">How it works</a> · <a href="#architecture">Architecture</a> · <a href="#developing">Developing</a> · <a href="#contributing">Contributing</a> </p>

<p align="center"> <img src="docs/walkthrough.gif" alt="Guided review walkthrough: overview, assumptions, anchored diff stops, verification" width="820"> </p>

---

AI agents write code faster than anyone can read diffs — and the context that makes review fast (what was asked, what was assumed, what was tried and abandoned, what was tested) is thrown away the moment the PR opens. Review Assist captures it at the source: an agent's session becomes an Intent Document, a validator proves it actually covers the diff, and a GitHub App renders it as a guided review on top of the pull request.

Fully open source, self-hostable, and stores none of your code. Your session transcript never leaves your machine. The app has no database: it reads the document and diff from GitHub per request with the reviewer's own token, keeps them in memory for the length of that request, and serves them private, no-store to a viewer that renders in the reviewer's browser. Nothing is written down, but your code does pass through the service in transit — if that matters to you, self-host it.

Install

Two one-time installs — the MCP server on the developer's side, the GitHub App on the repo's.

1. Register the MCP server with your agent (so it can author Intent Documents).

Claude Code:

claude mcp add -s user review-assist -- npx -y review-assist-mcp

Codex:

codex mcp add review-assist -- npx -y review-assist-mcp

Both write the same entry to the agent's own config — for Codex that's ~/.codex/config.toml, shared with the IDE extension. Check it landed with codex mcp list (or claude mcp list).

If you use the VS Code extension or a GUI-launched editor, register it without npx instead. GUI apps on macOS get only /usr/bin:/bin:/usr/sbin:/sbin, so a Homebrew or nvm npx is not on the path; on Windows npx is a .cmd wrapper that fails without a TTY, and the VS Code panel has none. Either way the server shows as not connected with no error. Invoking node directly avoids both:

npm install -g review-assist-mcp
claude mcp add -s user review-assist -- "$(which node)" "$(npm root -g)/review-assist-mcp/dist/index.js"

Both $(...) expand on your machine, so it is correct for Homebrew, nvm, fnm, Volta and Linux alike. nvm users: re-run it after switching Node versions.

If you would rather not install globally, launching VS Code from a terminal with code . makes it inherit your shell's PATH, and the npx command above then works. That is a habit rather than a setting, though — open the editor from the Dock once and the server quietly stops connecting.

Claude desktop app — one-click, no terminal: download the .mcpb and open it.

2. Install the GitHub App →

One click. Read-only code + PR comments, no workflow files — it adds the automatic check on every PR, the summary comment, and the guided-review viewer.

How it works

<p align="center"> <img src="docs/how-it-works.svg" alt="How it works, in three steps. 1 Code, on your machine: your agent writes the change and an Intent Document that explains it — the ask, the assumptions, a tour of the diff — committed alongside the code; the transcript never leaves the machine. 2 Validate, on GitHub with no code stored: a GitHub App proves the document covers the diff (schema, staleness, cross-refs, redaction), reports coverage such as 5 of 5 changes explained, and posts an Open guided review link on the pull request. 3 Review, in the reviewer's browser: check the assumptions first — flagging one posts it to the PR discussion — then take the anchored tour and approve or request changes; the verdict posts to the pull request as you, and merging stays on GitHub." width="620"> </p>

Architecture

<p align="center"> <a href="docs/architecture.svg"> <img src="docs/architecture.svg" alt="Container-level topology: three systems and two external actors. The developer machine runs the coding agent and the MCP server and writes the Intent Document, with the transcript staying local. GitHub holds the pull request, the committed document, the automation output and the reviewer's comments and verdict. The Review Assist Application receives pull_request events on its webhook, posts the check run, summary and PR-description block as its bot identity, and serves the guided review, reading and writing GitHub as the signed-in reviewer." width="820"> </a> </p>

Three systems and two external actors. Your machine produces the change and its Intent Document; the session transcript never leaves it. GitHub holds the pull request and every durable piece of review state. The application reacts to pull_request events and posts the check as its bot identity, then serves the guided review, reading and writing GitHub as the signed-in reviewer.

The two-agent distillation — author and reviewer as separate role-locked contexts, and the tools each one may reach — is a component-level view, kept in docs/ARCHITECTURE.md along with the full route list.

Developing

Path	Component
packages/schema	The format — JSON Schema (draft 2020-12) + TypeScript types
packages/validator	review-assist CLI + library: the five checks and the Markdown renderer
packages/mcp-server	MCP server that drives distillation and gatekeeps submissions
apps/github-app/worker	Stateless Cloudflare Worker: OAuth broker + thin GitHub proxy
apps/github-app/viewer	Client-side guided-review viewer
SPEC.md	The frozen design: the document's six sections and the five checks

npm install
npm run build

# Validate and render the example Intent Document
node packages/validator/dist/cli.js validate packages/schema/src/example.json
node packages/validator/dist/cli.js render packages/schema/src/example.json

# Preview the guided viewer with mock data → http://localhost:8787/#acme/checkout-service/pull/42
node scripts/mockserver.mjs

# Tests
npx vitest run

Architecture and internals: docs/ARCHITECTURE.md.

Contributing

Issues and pull requests are welcome. If the guided review reads wrong on one of your pull requests, open an issue with the Intent Document and the diff that produced it — that pair is usually enough to reproduce. Proposals to change the format itself are worth raising as an issue first, since SPEC.md is deliberately frozen and any change ripples through the validator, the viewer, and every document already committed.

Before opening a pull request, run the checks under Developing; CI runs the same build, typecheck, tests, and example validation.

License

Apache-2.0.