# Where your data lives

> The ~/.local-review directory, its layout, automatic snapshots and how to restore from them.

Everything you create (projects, PR title and description overrides, review comments, Viewed marks) lives in plain
files in a dot-directory in your home, like `~/.claude`. It is never in the repos you review and never in Local
Review's own install, so Local Review can be updated or reinstalled without touching anyone's reviews. It isn't
version-controlled; [snapshots](#snapshots) cover that. The one thing that isn't here is text you haven't saved yet:
[drafts](/using/editing-pr-text/#drafts) are kept in the browser's localStorage, and never sent anywhere until you save
them.

```text
~/.local-review/                        # or $LOCAL_REVIEW_HOME
  projects/
    <slug>/                             # one per project; the slug is used in URLs: /<slug>/<repo>/<sha>
      project.yaml                      # which repos and commits, and how they're split into PR stacks
      prs/<repo>/<full-sha>.yaml        # optional PR title/description overrides, readiness, branch, GitHub PR, landed
      reviews/<repo>/<full-sha>.yaml    # review comments and Viewed marks
      assets/<hash>.<ext>               # images shown in descriptions, stack notes and the intro
      assets/<hash>.<ext>.yaml          # optional: where an image is published (url:), for plan
      …/*.yaml.bak                      # files set aside, never deleted (below)
  backups/
    2026-10-09T08-45-12Z/               # automatic snapshots: a plain copy of projects/ at that time (UTC)
  examples/                             # only if you added the example projects
    orchard-<id>/                       # their git repos and a manifest.json (made by Local Review; see below)
  cache/
    <hash>.json                         # what git said about each repo's commits (disposable; see below)
  github/                               # only if you use GitHub status (disposable; see below)
    <owner>/<repo>/<number>.json        # what GitHub says about one published PR
    <owner>/<repo>/sync.json            # that GitHub repo's last fetch, and its error if it failed
  config.yaml                           # optional: settings for this machine (the GitHub sync)
  runtime.json                          # while `local-review` runs: its pid, port, URL and version (see below)
  update-check.json                     # what `local-review update --check` or `doctor` last found (see below)
  update.lock                           # only while `local-review update` runs
  logs/                                 # only if you run it as a service
    service.log                         # the service's output (see below)
    service.log.1 … .3                  # older output, once it has been rotated
```

| File | Written by | Reference |
| --- | --- | --- |
| `project.yaml` | you (`local-review init` creates it), an agent, and the UI for the intro and stack notes | [project.yaml](/reference/project-yaml/) |
| `prs/<repo>/<sha>.yaml` | the UI (title, description, Draft/Ready) and an agent (branch, GitHub PR, landed); `local-review move` copies them between projects | [PR files schema](/reference/pr-files/) |
| `reviews/<repo>/<sha>.yaml` | the UI (your comments, Viewed) and an agent (its replies); `local-review move` copies them between projects | [Comment files schema](/reference/comment-files/) |
| `assets/<hash>.<ext>` | `local-review asset add`, and pasting, dropping or attaching an image in the UI; `local-review move` copies the ones moved descriptions show | [Images](#images) |
| `assets/<hash>.<ext>.yaml` | `local-review asset url`, an agent or you | [Images](#images) |

Every file under `projects/` is watched, and what the server works out from them (and from the repos' branches,
polled every 2 seconds while a browser has a page open) is only kept while they're unchanged, so edits from an agent or an editor show up in the
browser within about a second, with no restart.

**`cache/`** holds one file per repo with what git said about its commits: each commit's subject, author and changed
files, merge-bases, ancestry and patch-ids. A commit's sha fixes all of that, so the entries never go stale, and after a
restart the first page load asks git only where the branches point (a couple of dozen git processes, rather than
several per commit). It's not your data and isn't in snapshots: delete it any time, and it's rebuilt as pages load.
It's off when only `LOCAL_REVIEW_PROJECTS_DIR` is set (like snapshots).

<a id="github"></a>**`github/`** holds what [GitHub status](/using/github-status/) fetched: one JSON file per published
PR, under its GitHub owner and repo (lower-cased), with its state, approvals, checks, review threads (each with its
`state`: `resolved`, `answered` or `open`, its file and line, and its comments' text), reviews and comments; and a
`sync.json` per GitHub repo, with when it was last fetched and the last attempt's error. Written only by the GitHub
sync (the server, or `local-review github refresh`), never by you or an agent. It's a cache, not your data, and isn't
in snapshots: delete it any time, and the next fetch rebuilds it. Off when only `LOCAL_REVIEW_PROJECTS_DIR` is set.

**`config.yaml`** is optional: settings for this machine rather than any one project. See
[config.yaml](/reference/config-yaml/).

**`runtime.json`** is there while Local Review runs (`local-review`, or the service): its pid, port, URL, version and
start time, readable only by you, so [`local-review busy`](/reference/cli/#local-review-busy) can find it. It writes it
on start and removes it when it exits (see the [never-delete guarantee](/guarantees/never-delete/)). It's
never your data. One left behind by a crash is ignored, because its pid is gone. A development server (`npm run dev`)
doesn't write it.

**`update-check.json`** is what the last [`local-review update --check`](/getting-started/updating/) (or `update`, or
`doctor`) found on npm: the newest version, whether it's newer than yours, and when it asked. `service status` repeats
it, without asking npm itself. **`update.lock`** holds the pid of an `update` while it runs, so two can't run at once;
it's removed when it ends, and one left by a crash is ignored once its pid has gone. Neither is your data.

**`logs/`** is there only if you [run Local Review as a service](/getting-started/service/): launchd or systemd appends
its output, stdout and stderr both, to `service.log`, which `local-review service logs` reads. A service installed
before 0.14 wrote `server.out.log` and `server.err.log` instead; they're left here after `service restart` moves it to
`service.log`. Local Review rotates `service.log` itself: when it starts, and every 15 minutes while it runs, a log
past 8 MB is copied to `service.log.1` and truncated in place (launchd and systemd hold it open, so it can't be
renamed), older copies shift down, and three are kept. Empty or delete any of them whenever you like. `local-review service uninstall`
leaves them, like everything else here. The service's own file isn't here: it's in `~/Library/LaunchAgents` or
`~/.config/systemd/user` (`$XDG_CONFIG_HOME/systemd/user` if that's set).

**Set-aside files.** Local Review never deletes a file; when one has to go out of the way, it's renamed to a `.bak`,
which nothing reads:

| Name | Why |
| --- | --- |
| `<sha>.superseded-by-<sha8>.yaml.bak` | A prs or reviews file whose comments moved to a rebased commit's file ([Following rebases](/concepts/following-rebases/)). |
| `<sha>.moved-to-<project>.yaml.bak` | A prs or reviews file `local-review move` copied into another project ([CLI](/reference/cli/#local-review-move)). |
| `project.example-removed.yaml.bak` | An example project hidden by **Remove examples**; adding them again renames it back. |

**The example projects** (`local-review examples`, or the button on the first-run page) are ordinary projects named
`projects/example-*`, with `example: true` in their `project.yaml`, reviewing four git repos that Local Review creates
under `examples/`. Removing them renames each `project.yaml` to `project.example-removed.yaml.bak`; nothing is deleted
([details](/reference/cli/#local-review-examples-remove)).

**Getting started:** `npx local-review init my-feature` creates `~/.local-review/projects/my-feature/project.yaml`
from a commented example (it never replaces an existing one); then edit it. With no projects, the UI's first-run page says the same, and offers the example projects.

## Images

A project's images live in its `assets/` folder. Markdown refers to them as `assets/<name>`, for example
`![Overview](assets/3f2a9c1e0b7d4a65.png)`, and the UI shows them in PR descriptions, stack notes and the project
intro (see [Images](/using/editing-pr-text/#images)).

- **Named by content.** The name is the first 16 hex digits of the file's SHA-256, plus `.png`, `.jpg`, `.gif`,
  `.webp` or `.svg`. Adding the same image twice is a no-op, and nothing else can be called that.
- **Checked.** PNG, JPEG, GIF, WebP and SVG only, up to 5 MB. The bytes must really be the type the file claims to be
  (by their magic numbers; an SVG must start with an `<svg` root element).
- **Written once.** An asset is created and never replaced or removed. Nothing in Local Review deletes one, even if
  no description uses it any more; delete unused ones by hand if you want the space back.
- **`<name>.yaml`** beside an image can record where it's published, as `url: https://…`. `local-review plan` then
  puts that URL in the PR bodies in place of `assets/<name>`, because GitHub can't show a file on your machine (see
  [Publishing](/agents/publishing-stacked-prs/#images)). Write it with `local-review asset url <project> <name> <url>`,
  or by hand; any other fields in it are kept.

## Moving it

`LOCAL_REVIEW_HOME` moves the whole data directory, e.g. for a scratch instance next to your real one:

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

`LOCAL_REVIEW_PROJECTS_DIR` moves only `projects/`. It's for the tests, and it turns automatic snapshots off unless
`LOCAL_REVIEW_HOME` is set too. See [Environment variables](/reference/environment/).

## Snapshots

When the server starts, and then every hour while it runs, it copies `projects/` to `backups/<timestamp>/` (with file
times preserved), but only if something changed since the newest snapshot.

- A snapshot is copied under a hidden `.partial-…` name and renamed when complete, so every timestamped directory is
  a full copy.
- It keeps the **50 most recent** snapshots, plus the **first snapshot of each day for 30 days**.
- Pruning only ever removes directories directly inside `backups/` whose names are snapshot timestamps (not
  symlinks, not anything else you put there), and never the newest.
- Images are **hard-linked** into a snapshot rather than copied (where `backups/` is on the same file system), so
  every snapshot shares one copy of each image on disk instead of adding up to 5 MB per image per hour. That's safe
  because an asset's name is its content and Local Review never changes one in place. Editing an asset file in place
  with another tool would change it in the snapshots too; don't (add the edited image as a new asset instead).

That pruning is the only deletion Local Review ever does; see the [never-delete guarantee](/guarantees/never-delete/).

## Restoring

Restoring is copying files back, by hand. Stop the server first if you're restoring a lot. For example:

```sh
ls ~/.local-review/backups/                                       # pick a snapshot
diff -r ~/.local-review/backups/<timestamp>/<slug> ~/.local-review/projects/<slug>
cp -p ~/.local-review/backups/<timestamp>/<slug>/reviews/<repo>/<sha>.yaml ~/.local-review/projects/<slug>/reviews/<repo>/
```

Deleting a comment in the UI (you can only delete your own) removes it from the file, as you'd expect; the previous
version is in the snapshots.
