Guided Review

Review AI-generated code before you sign your name to it.

Guided Review turns GitHub pull requests and local git changes into an ordered walkthrough of review units so you can read the change with intent instead of reconstructing it from an alphabetical file list.

1. Run npx @guided-review/cli in your project directory (or click on Start Guided Review on a GitHub PR if you're using the Chrome Extension)
2. When you ask for AI structure, your LLM clusters related hunks and adds short commentary — schema, then logic, then call-sites, then tests.
3. Follow the walkthrough keyboard-first. The code always comes from the real diff; you still read it and decide.

Free, open source, bring your own LLM key. Guided Review has no product backend: the extension and CLI talk directly to your AI provider, and the extension talks to GitHub for PRs.

• Chrome extension — Chrome Web Store, or build from source below
• CLI — npx @guided-review/cli (npm)

Site and docs: guidedreview.dev · docs.

• Demo
• Why?
• Getting Started
  • Chrome extension
  • Local CLI
  • Development
  • Building
  • Testing
• Usage
• Configuration
• License

Why?

Automated review agents help find bugs and edge cases you missed — useful — but they are not a replacement for you. They lack taste: product context, people, when an abstraction is unnecessary, when to break the rules.

Even with AI today, nothing beats reading the code. GitHub still hands you every changed file in alphabetical order; a raw git diff is no better. That was awkward for human-written diffs; for large AI-shaped changes it is actively hostile.

Guided Review uses AI only where it helps: clustering related hunks into a walkable order and adding short summaries you can take or ignore.

The Chrome extension does this on GitHub PRs. This CLI does the same for local work — before you open the PR, or when there is no PR at all.

Getting Started

Chrome extension

From the store: install from the Chrome Web Store, open Options → add an LLM API key → open a GitHub PR → Start Guided Review.

From source — requires Node.js ≥ 22, pnpm ≥ 11, and Chrome:

1. Install dependencies from the monorepo root:

pnpm install

2. Build the extension:

pnpm build:extension

3. Load it in Chrome:

   • Open chrome://extensions
   • Enable Developer mode
   • Load unpacked → select apps/extension/dist (never a root-level dist/)

4. Open Options → add an LLM API key → open a GitHub PR → Start Guided Review

Local CLI

Requires Node.js ≥ 22. No clone needed:

npx @guided-review/cli

The CLI starts a local server on 127.0.0.1, opens a browser UI, and walks the current branch versus its base, uncommitted work, or a single commit. It starts file-by-file and does not call an LLM until you click Structure With AI.

npx @guided-review/cli --base main --no-open
npx @guided-review/cli --staged --agent claude-code

The binary is guidedreview. Full detail: CLI · apps/cli/README.md.

From this repo after pnpm install:

pnpm build:cli
pnpm review
pnpm review -- --base main --no-open

Development

For day-to-day work with HMR:

pnpm dev                 # extension Vite / crx on port 5173
pnpm dev:cli             # CLI UI + server
pnpm dev:web             # marketing site → http://localhost:3000

After extension code changes, rebuild if needed (pnpm build:extension), Reload the extension card in chrome://extensions, and refresh the PR tab. Chrome serves whatever is currently in dist/ — a running dev server alone does not replace that reload.

More detail: apps/extension/README.md · apps/cli/README.md · apps/web/README.md.

Building

pnpm build:extension     # typecheck + Vite → apps/extension/dist (+ zip)
pnpm build:cli           # CLI binary + UI → apps/cli/dist
pnpm build               # every workspace package with a build script (extension, site, CLI)
pnpm build:web           # Next.js static export → apps/web/out

Testing

From the monorepo root:

pnpm test                    # unit tests (extension + UI)
pnpm test:e2e:install        # Chromium for extension e2e (once)
pnpm test:e2e                # extension Playwright e2e (builds first)
pnpm test:e2e:web            # marketing site e2e (builds first)
pnpm test:e2e:cli            # CLI Playwright e2e (builds first)

Also available: pnpm typecheck, pnpm lint, pnpm format. Workspace-scoped runs use pnpm --filter @guided-review/<package> <script>.

Usage

On a GitHub pull request — click Start Guided Review (or open from the extension once you are on the PR). The overlay walks you through review units — related hunks grouped and ordered — with keyboard shortcuts for next/prev unit, commenting, and submit.

• Without an API key, you still get a one unit per file fallback so navigation and comments work; connect a provider for clustered plans.
• Reading a PR and generating a plan does not require GitHub OAuth. Submitting a review (approve / comment / request changes) does — device flow, public client id only.
• Line comments attach to the real diff lines shown for a unit, not to model-invented code.

Docs: Your first review · Keyboard shortcuts · Submit a review.

On local changes — run the CLI in a git repo, pick the scope (branch vs base, uncommitted, unstaged, or a commit), then use Structure With AI when you want related files grouped into review units with short context. Line notes stay in the running session; there is no GitHub submit. Generate Prompt builds a coding-agent prompt from those notes and copies it — Guided Review does not send it anywhere.

Docs: CLI.

Configuration

LLM provider — Anthropic, OpenAI, or Grok, with your own API key.

• Extension — Options page; keys live in chrome.storage.local on your machine. See Configure AI provider.
• CLI — Settings in the local UI, env vars (ANTHROPIC_API_KEY / OPENAI_API_KEY / XAI_API_KEY or GROK_API_KEY), ~/.config/guided-review/config.json, or a coding agent already on the machine (Claude Code, Codex, Grok). See CLI.

GitHub OAuth (extension, optional) — needed only to submit reviews from the overlay. Create an OAuth App with Device Flow enabled, then at the monorepo root:

cp .env.example .env        # set VITE_GITHUB_CLIENT_ID
pnpm build:extension

Full setup: apps/extension/README.md — GitHub OAuth.

Monorepo — pnpm workspaces:

Path	What
apps/extension	Chrome MV3 extension (GitHub PRs)
apps/cli	Local git review CLI (npx @guided-review/cli)
apps/web	Marketing site and docs (Next.js)
packages/core	Review engine (parse, cluster, summarise)
packages/ui	Shared tokens, brand assets, presentational UI

Package READMEs own architecture, deploy, and contribution detail for each.

License

Licensed under the Apache License, Version 2.0.