Review local changes

The Chrome extension still reviews GitHub pull requests. The CLI reviews a local branch, a commit, or your working tree, using the same engine and walkthrough. It does not start an AI plan until you ask.

Run it

From this repo (the CLI is not on npm — npx guided-review is a different package):

npm install
npm run build:cli
npm run review

Pass flags after --:

npm run review -- --base main --no-open

The CLI binds 127.0.0.1:7182 (ASCII G+R), keeps a short terminal banner (URL, diff, last pull), and opens the UI unless you pass --no-open. Only real events (structure, scope change, errors) go to the log below. Override with --port. --port 0 picks any free port. Ctrl+C stops the server.

What it compares

The header shows the current branch and the base branch. A dropdown picks the diff:

• Branch vs base — committed work on this branch since it diverged from the base (git diff <merge-base> HEAD)
• Uncommitted — staged and unstaged work versus HEAD (untracked files included unless you passed --no-untracked)
• Unstaged — worktree versus the index only
• A specific commit — that commit’s patch

Default selected scope: the first non-empty of branch, uncommitted, unstaged, then the newest commit. --staged starts on index-only uncommitted work.

Base resolution, in order: --base → origin/HEAD → main → master.

If every scope is empty: Nothing to review against <base>. and exit 0. Not a git repo: an error that says what failed.

The walkthrough starts one unit per file. Structure with AI on the Change summary card is the opt-in LLM call. It groups files and adds context — it does not review for you. Press d to open the dropdown, ⌘/Ctrl + I to structure, or ⌘/Ctrl + , for Settings — same keys as Keyboard shortcuts.

API keys

Same providers as the extension: Anthropic, OpenAI, Grok.

Resolution, in order:

1. --provider / --model / --agent and env (ANTHROPIC_API_KEY / OPENAI_API_KEY / XAI_API_KEY or GROK_API_KEY)
2. A key already saved in ~/.config/guided-review/config.json
3. A coding agent already on this machine (Claude Code, Codex, or Grok)

If more than one agent has a usable key, the CLI asks which to use each run (Enter keeps the last choice). The chosen agent is shown in the browser UI. It reads the agent's own store at review time and does not copy the secret into Guided Review config.

No key still walks one unit per file. Structure with AI asks for a key.

The local UI has Settings (header, ⌘/Ctrl + ,, or Connect AI Provider when no key is set). Paste an API key, or turn on Use my subscription to borrow Claude Code / Codex / Grok on this machine. A saved API key always wins. Subscription is unofficial and can break — a console key is the better option. Save writes ~/.config/guided-review/config.json (or $XDG_CONFIG_HOME / GUIDED_REVIEW_CONFIG_DIR). Flags and env still win for that run.

Notes

Line comments stay in the 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.

Flags

npm run review -- [dir] --base main --port 8787 --no-open --staged --no-untracked --agent claude-code