# Quickstart

> Run Local Review with npx, create your first project, and review a branch as a stack of PRs.

import { Steps } from '@astrojs/starlight/components';
import { DEFAULT_PORT, LOCAL_URL } from '../../../site.mjs';

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

<Steps>

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

   ```sh
   npx local-review
   ```

   <p>It serves the UI on <a href={LOCAL_URL}>{LOCAL_URL}</a>. With no projects yet, that's a welcome page that
   tells you how to create one, which is the next step. Leave it running.</p>

   <p>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 <code>npm i -g local-review &amp;&amp; local-review service install</code>
   (<a href="/getting-started/service/">Run it as a service</a>). From then on, every command here works without
   <code>npx</code>.</p>

   ![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](../../../assets/shots/welcome.png "What a brand-new install shows at /.")

   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](/concepts/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](/reference/cli/#local-review-examples-remove)).

2. **Create a project.** In another terminal, pick a short name (a *slug*) for the piece of work you want
   reviewed:

   ```sh
   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](/using/ui-tour/#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:

   ```yaml title="~/.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](/reference/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](../../../assets/shots/single-repo-project.png "A project with one repo and no `stacks:` yet: the whole range is one stack, named after the branch.")

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](/agents/hand-off-prompt/) into your agent, or start with the [agent guide](/agents/agent-guide/).

</Steps>

## 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](/reference/data-directory/).

To keep it somewhere else, set `LOCAL_REVIEW_HOME`, for example to try Local Review out without touching your
real reviews:

```sh
LOCAL_REVIEW_HOME=/tmp/lr-demo npx local-review
```

<p>
	To use a port other than {DEFAULT_PORT}, pass <code>--port &lt;n&gt;</code> or set <code>PORT</code>. See{' '}
	<a href="/reference/environment/">Environment variables</a> for the rest.
</p>

## Next steps

- [Run it as a service](/getting-started/service/): keep it running in the background, started at login.
- [PR stacks](/concepts/pr-stacks/): how stacks are chosen, and why they survive rebases.
- [Works with your stacking tool](/concepts/stacking-tools/): where Local Review fits next to `gh stack`, Graphite,
  ghstack and the rest.
- [A tour of the UI](/using/ui-tour/): what everything on the screen means.
- [Linked projects](/concepts/linked-projects/): when one piece of work builds on another.
- [Read-only guarantee](/guarantees/read-only/): why Local Review can't damage your repos.
