Skip to content

akarachen/guided-review

v0.1.0MIT

Review pull requests and produce evidence-backed Guided Review artifacts.

Guided Review

Turn any pull request into a readable map — every claim backed by real code.

CI License: MIT Rust Agent skill

English  ·  中文


Why Guided Review?

You open a 60-file pull request. The description says one thing, the diff says forty. You scroll file by file, lose the thread, and end up approving on vibes — or blocking on a nit while the real risk ships.

Review tools got better at showing diffs. They never got better at explaining them. And now that AI writes more of the code, the bottleneck is no longer writing changes — it is understanding them.

Guided Review is built on a simple idea: a review artifact should reduce comprehension cost, not add ceremony.

How It Works

your agent reads the diff  ──▶  writes a review payload  ──▶  egr renders one page
        (any coding agent)        (JSON, schema-checked)        (self-contained HTML)
  1. The skill drives the review. Your coding agent inspects the diff, reconstructs the change, and writes a JSON payload following the schema printed by egr generate -h.
  2. The renderer enforces honesty. Claims without code excerpts, excerpts with the wrong line count, and approvals that contradict their own blockers are rejected before any HTML is written.
  3. You read one page. Thesis, reading order, line map, risks, verification status, and a recommendation — every statement linked to syntax-highlighted lines from the real diff.

Install

# the egr CLI
cargo install --git https://github.com/AkaraChen/guided-review guided-review

# Claude Code plugin
claude plugin marketplace add AkaraChen/guided-review
claude plugin install guided-review@guided-review

# Codex plugin
codex plugin marketplace add AkaraChen/guided-review
codex plugin add guided-review@guided-review

# standalone agent skill
npx skills add akarachen/guided-review

The repository root is also an Agent Plugins 1.0 package: plugin.json at the root plus the skill under skills/guided-review/. Any Agent Plugins-compatible client can install it from the repository directly.

Quick Start

egr claude --pr owner/repo#123      # launch Claude Code with a PR review prompt
egr cc --staged                     # `cc` is the visible alias for `claude`
egr codex --branch main             # review the current branch with Codex
egr codex --worktree --print        # inspect the prompt without launching an agent
egr generate -h                   # prints the review JSON Schema
egr generate owner/repo#123 --review review.json --output out/index.html
egr serve out                     # serves on 127.0.0.1, prints the URL

Agent commands also accept --commits RANGE, --paths PATH..., and forwarded native arguments after --. With no explicit scope, egr selects an ahead branch first, then a changed worktree. Use --headless for claude -p or codex exec, and --dry-run to inspect the final process arguments.

See examples/review.json for a complete payload and skills/guided-review/SKILL.md for the agent workflow.

The Philosophy

Evidence or it didn't happen

Every statement in a Guided Review — the thesis, each risk, each answer — must cite real lines from the diff. A review you can't verify is a review you can't trust.

A map, not a summary

A file-by-file summary tells you what you could already see. A Guided Review reconstructs the change as a system: a one-sentence thesis, a suggested reading order, the visible and hidden lines of the change, and the risks that deserve human attention.

Judgment stays human

AI drafts the map; humans own the merge decision. Every claim is labeled as observed or synthesis, so a reviewer always knows which statements were read directly from the code and which were concluded from it.

What You Can Do

Read one page instead of sixty files

  • A self-contained HTML page per pull request — no server, no account, no build step to view it.
  • Suggested reading order tells you where to start and why.
  • Every claim links to syntax-highlighted excerpts with exact file and line references.

Judge risk, not diff order

  • Risks classified as blocker, should-fix, or follow-up.
  • Verification status per claim: verified, partial, or unproven.
  • A final recommendation with blockers kept separate from polish.

Let your agent do the legwork

  • A JSON contract, printed as a schema from egr generate -h, that any coding agent can fill.
  • A ready-made agent skill in skills/guided-review/ that drives the whole workflow: inspect the diff, write the payload, render, and serve.
  • egr serve previews the result locally and shuts itself down when you close the tab.

Who It's For

Guided Review is for engineers who:

  • review large or AI-generated pull requests and want the story, not the noise;
  • run coding agents and want review artifacts they can actually audit;
  • believe an approval should mean "I understood this", not "I scrolled this".

The Vision

Code review is becoming the narrowest part of the software pipeline. We think the fix is not faster skimming — it is artifacts that make understanding cheap and verification mandatory. Guided Review wants to be the format a reviewer reaches for the way they reach for a diff today.


Made by @AkaraChen · Reviews are read by humans, proven by code.