local-review
v0.17.0
Published
Review a stack of local commits like a stack of GitHub PRs, before any of them is pushed. Comments live in plain YAML files your coding agent can read and reply to.
Maintainers
Readme
Local Review is a GitHub-style pull-request UI for the stack of commits on your machine, before any of it is pushed. Every commit is shown as its own PR, grouped into the stacks you mean to open. You review them like PRs, your coding agent reads your comments and replies in the same place, and when a stack is right, the agent publishes it as GitHub stacked PRs.
- Every commit is a PR, with a Conversation tab, a Files changed tab, a Stack tab and a readiness badge, grouped into colour-coded PR stacks, across one repo or several.
- Every effort in view. The root page shows each project as a card with a thumbnail of its stacks, and work that builds on other work is linked to it, in order.
- Your agent answers in the review. Comments are plain YAML files that any coding agent can read and reply to; the replies show up in your browser live, and threads follow their code through amends and rebases. A stack's or project's Comments tab gathers every thread on its PRs in one list, and what you type is kept as a draft until you send it.
- Publish when it's ready.
local-review planprints each PR's branch, base, title and body, and your agent opens the stack as GitHub native stacked PRs, posting the comments you marked for the GitHub PR. It works in front of any stacking tool. - Safe to point at your work. It never modifies your repos, never talks to GitHub, never deletes your review, and only listens on localhost.
Quickstart
Needs Node.js 22 or later and git, on macOS or Linux. To look around first, run npx local-review and click Add
the example projects: a made-up app reviewed across four repos.
npx local-review init my-feature # create ~/.local-review/projects/my-feature/project.yaml
npx local-review # serve the UI on http://localhost:5622Edit project.yaml to point at your repo, branch and stacks:
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
- title: The feature itself
starts_at: "Add the feature flag" # the subject of the commit the stack starts atThen open http://localhost:5622. Edits are picked up live. The full walk-through is the Quickstart.
To keep it running in the background, started at login (a LaunchAgent on macOS, a systemd user unit on Linux):
npm i -g local-review
local-review service installSee Running as a service.
Upgrading from before 0.2.0? The default port was 5000; it's now 5622 (macOS uses 5000 for AirPlay). Update bookmarks and agent prompts, or run
npx local-review --port 5000.
For agents
To have your coding agent set up a project, point it at the running server's llms.txt:
Read http://localhost:5622/llms.txt and create a local-review project for my feature-xyz branch on ~/code/my-git-projectIt has the rules, the recipe, the commented project.yaml example and this machine's data directory and projects
(llms.txt; the docs site has a copy at
https://local-review.edspencer.net/llms.txt). Then
npx local-review guideprints the guide for coding agents driving Local Review from the repo they work on: the data model, how to answer review threads, fix a commit mid-stack, tag branches, publish stacked PRs and record merges. It's AGENT-GUIDE.md in this repo, and on the docs site. To hand a reviewed project to your agent, paste the hand-off prompt.
Documentation
https://local-review.edspencer.net
- Getting started: Quickstart · Installation · Running as a service
- Concepts: Projects & repos · PR stacks · Readiness · Landed PRs · Follow-on stacks · Linked projects · Following rebases
- Using it: A tour of the UI · Reviewing & comments · Editing PR text · Stack pictures · Keyboard shortcuts
- For agents: Agent guide · llms.txt · Publishing stacked PRs
- Reference: CLI · project.yaml · Comment files · HTTP API · Where your data lives
- What's new
Guarantees
- Read-only: it never fetches, checks out, commits or rebases; all git access to your repos goes through one read-only allow-list. Read-only guarantee
- Never deletes: your review lives in
~/.local-review, never in your repos; writes are atomic, nothing is unlinked, and it's snapshotted hourly. Never-delete guarantee - Localhost only: it binds 127.0.0.1 and rejects non-localhost
HostandOriginheaders. Localhost security
And so you can't mistake it for github.com, its header is deep plum with an amber underline and a "not on GitHub" pill.
Contributing
Contributions are welcome: see CONTRIBUTING.md, and AGENTS.md for coding agents working on this repo. Report vulnerabilities privately as described in SECURITY.md. How AI was used to build it: AI-DECLARATION.md. Releases: RELEASING.md.
License
MIT, see LICENSE.
The fonts bundled in server/fonts/ for the stack picture are Inter and
JetBrains Mono, both under the SIL Open Font License 1.1
(server/fonts/*-OFL.txt). npm dependencies keep their own licenses.
