Quickstart
You need Node.js 22 or newer and git. Local Review runs on macOS and Linux. (Windows is untested.)
-
Start Local Review. Run it from any directory:
Terminal window npx local-reviewIt serves the UI on http://localhost:5622. With no projects yet, that’s a welcome page that tells you how to create one, which is the next step. Leave it running.
Using it every day? Install it and let it run in the background, started at login: stop this one (Ctrl-C), since the service needs the port, then
npm i -g local-review && local-review service install(Run it as a service). From then on, every command here works withoutnpx.
Want to look around first? Add the example projects on that page (or run
npx local-review examples). They’re “Orchard”, a made-up booking app, as four projects across four repos: stacked PRs, review threads with an agent’s replies, two linked projects and an archived one whose PRs have all merged. Later the same button is at the bottom of the root page and the project switcher. Remove examples (in an example’s sidebar, or Remove example projects on the root page) hides them again; nothing is deleted (details). -
Create a project. In another terminal, pick a short name (a slug) for the piece of work you want reviewed:
Terminal window npx local-review init my-featureThis creates
~/.local-review/projects/my-feature/project.yaml, a commented starting point. The page at/becomes the root page, with your project as a card (with no PRs yet: the example repo path in it doesn’t exist). -
Point it at your branch. Edit
project.yamland list the repo, the branch to review and the base it branched from. Then split the commits into stacks by the subject of the commit each stack starts at:~/.local-review/projects/my-feature/project.yaml title: My featurerepos:- path: ~/code/my-servicebranch: me/my-feature # the range ends at this branch's headbase: origin/main # and starts at its merge-base with thisstacks:- title: Groundworkstarts_at: "Add the config loader"- title: The feature itselfstarts_at: "Add the feature flag"Leave
stacks:out and the whole branch is one stack. A project can list several repos. Every field is on project.yaml. -
Review. Save the file and the browser picks it up; no restart is needed. Open the project’s card: each commit is now a PR in the sidebar, in its stack, and Start with #1 … opens the first. Read the diffs, leave comments, tick files as Viewed, and mark each PR Ready when you’re happy with it.

-
Hand it to your agent. Your comments are saved as plain YAML next to
project.yaml. Point your agent at them and it can reply, fix the commits and, when you’re ready, publish the stacks to GitHub. Paste the hand-off prompt into your agent, or start with the agent guide.
Where your data lives
Section titled “Where your data lives”Everything you create lives in plain files in ~/.local-review/, never in the repos you review:
~/.local-review/ projects/ my-feature/ project.yaml # repos, commit ranges and PR stacks prs/<repo>/<full-sha>.yaml # PR title/description overrides, readiness, branch, GitHub PR reviews/<repo>/<full-sha>.yaml # review comments and Viewed marks backups/ # automatic snapshots of projects/Snapshots, restoring and the rest: Where your data lives.
To keep it somewhere else, set LOCAL_REVIEW_HOME, for example to try Local Review out without touching your
real reviews:
LOCAL_REVIEW_HOME=/tmp/lr-demo npx local-reviewTo use a port other than 5622, pass —port <n> or set PORT. See
Environment variables for the rest.
Next steps
Section titled “Next steps”- Run it as a service: keep it running in the background, started at login.
- PR stacks: how stacks are chosen, and why they survive rebases.
- Works with your stacking tool: where Local Review fits next to
gh stack, Graphite, ghstack and the rest. - A tour of the UI: what everything on the screen means.
- Linked projects: when one piece of work builds on another.
- Read-only guarantee: why Local Review can’t damage your repos.