Where your data lives
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 cover that. The one thing that isn’t here is text you haven’t saved yet:
drafts are kept in the browser’s localStorage, and never sent anywhere until you save
them.
~/.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 |
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 |
reviews/<repo>/<sha>.yaml | the UI (your comments, Viewed) and an agent (its replies); local-review move copies them between projects | Comment files schema |
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 |
assets/<hash>.<ext>.yaml | local-review asset url, an agent or you | 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).
github/ holds what 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.
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 can find it. It writes it
on start and removes it when it exits (see the never-delete guarantee). 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 (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: 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). |
<sha>.moved-to-<project>.yaml.bak | A prs or reviews file local-review move copied into another project (CLI). |
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).
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
Section titled “Images”A project’s images live in its assets/ folder. Markdown refers to them as assets/<name>, for example
, and the UI shows them in PR descriptions, stack notes and the project
intro (see Images).
- Named by content. The name is the first 16 hex digits of the file’s SHA-256, plus
.png,.jpg,.gif,.webpor.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
<svgroot 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>.yamlbeside an image can record where it’s published, asurl: https://….local-review planthen puts that URL in the PR bodies in place ofassets/<name>, because GitHub can’t show a file on your machine (see Publishing). Write it withlocal-review asset url <project> <name> <url>, or by hand; any other fields in it are kept.
Moving it
Section titled “Moving it”LOCAL_REVIEW_HOME moves the whole data directory, e.g. for a scratch instance next to your real one:
LOCAL_REVIEW_HOME=/tmp/lr-demo npx local-review --port 5050LOCAL_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.
Snapshots
Section titled “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.
Restoring
Section titled “Restoring”Restoring is copying files back, by hand. Stop the server first if you’re restoring a lot. For example:
ls ~/.local-review/backups/ # pick a snapshotdiff -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.