Skip to content

Quickstart

You need Node.js 22 or newer and git. Local Review runs on macOS and Linux. (Windows is untested.)

  1. Start Local Review. Run it from any directory:

    Terminal window
    npx local-review

    It 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 (Running as a service). From then on, every command here works without npx.

    The first-run welcome page: "Look around an example" with Add the example projects, and "Review your own work" with the init command and a prompt for your coding agent

    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).

  2. 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-feature

    This 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).

  3. Point it at your branch. Edit project.yaml and 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 feature
    repos:
    - path: ~/code/my-service
    branch: me/my-feature # the range ends at this branch's head
    base: origin/main # and starts at its merge-base with this
    stacks:
    - title: Groundwork
    starts_at: "Add the config loader"
    - title: The feature itself
    starts_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.

  4. 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.

    Local Review showing a one-repo project with no stacks configured: its commits form a single stack in the sidebar, and the first PR is open

  5. 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.

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:

Terminal window
LOCAL_REVIEW_HOME=/tmp/lr-demo npx local-review

To use a port other than 5622, pass —port <n> or set PORT. See Environment variables for the rest.