Core Concepts
Review Storage
Reviewed marks, comments, questions, AI artifacts, and session state are stored as files on disk. By default they live in managed application data — not in your repository — and are shared between the terminal and desktop apps per repo, branch, and view.
Why managed storage?
Keeping review sidecars out of your working tree means they never clutter git status, never need a
.gitignore entry, and never risk being committed by accident. Both front ends resolve the same path
for a given tab, so a review you start in the desktop app continues seamlessly in the terminal.
Where the root is
| Platform | Storage root |
|---|---|
| Linux | ~/.local/share/easy-review/ |
| macOS | ~/Library/Application Support/easy-review/ |
| Windows | %APPDATA%\easy-review\ |
Layout for local diff modes
Each local diff mode — branch, unstaged, staged and history — gets its own view bucket directory under the repo and branch. (The number in front of a mode in the tab bar is its position in the visible list, and that list grows when a tab knows its PR number, so a mode's number is not fixed.)
<root>/repos/<repo-slug>/branches/<branch-slug>/view-buckets/<bucket>/
where <bucket> is branch, unstaged, staged, or
history. For example, on Linux for the easy-review repo on main, branch diff:
~/.local/share/easy-review/repos/easy-review/branches/main/view-buckets/branch/
Layout for PR diff mode
Pull request reviews are keyed by owner/repo and PR number, so a local clone and a remote PR tab share one location:
<root>/repos/<owner-repo-slug>/prs/pr-<N>/
The <repo-slug> comes from the origin remote name (falling back to the repo folder
name). Slashes in branch names become -.
The sidecar files
The filenames are identical in managed storage and in repo-local mode:
| File | Written by | Purpose |
|---|---|---|
review.json | AI Hub: review (TUI “Review work” / desktop “Run review”) | Per-file risk levels and inline findings |
order.json | AI Hub: review | Suggested review order |
checklist.json | AI Hub: review | Review checklist items |
summary.md | AI Hub: review | Markdown summary of changes |
triage.json | AI Hub: Triage branch | Fast branch scan / routing |
professor.json | AI Hub: Professor | Teaching / learning insights |
experts/*.json | AI Hub: Specialized review | Domain-specific expert findings |
tour.json | AI Hub: Generate guided tour (TUI “Generate guided tour” / desktop “Generate tour”) | Guided-tour pillars and file order |
diagrams/*.json | AI Hub: Diagrams (desktop Context tab) | Mermaid diagrams of the diff (mental model, subsystems, flows, or custom) |
questions.json | er (q) | Personal review questions |
notes.json | er (draft type cycled with Ctrl+t) | Local actionable notes for agent hand-off |
github-comments.json | er (c) | GitHub PR comments |
session.json | er | Session metadata |
reviewed | er | Per-file reviewed markers |
Each JSON sidecar stores a SHA-256 diff_hash of the diff it was generated against. When the diff
changes, the matching AI data is dimmed with a stale warning. Writes are atomic (write to a temp file, then rename),
so a crash mid-write never corrupts your data.
Repo-local mode
Set ER_REPO_LOCAL=1 to read and write a .er/ directory inside the repository instead of
managed storage. This is useful for debugging, or for external tools that
write sidecar files into .er/ relative to the repo.
ER_REPO_LOCAL=1 er
In repo-local mode, add .er/ to your .gitignore so review artifacts are not committed.
With default managed storage, run reviews through er's built-in AI Hub (TUI: a /
Desktop: Cmd+K → AI). Use ER_REPO_LOCAL=1 only when an external
tool writes directly into
.er/ and you want er to read from the same location.
Migration from older versions
Earlier versions scattered sidecar dotfiles in the repo root, then consolidated them into a repo .er/
directory. Nothing copies either of those into managed storage: a legacy repo .er/ or
~/.cache/er/ directory is left where it is, and a current build starts from empty for that branch. To
keep reading an existing .er/, run with ER_REPO_LOCAL=1.
Tests & overrides
Set ER_STORAGE_ROOT=/tmp/... to redirect managed storage — primarily used by the test suite.
Cleaning up
From the terminal, z clears the questions and notes you wrote, and Z clears the AI review
sidecars (review.json, order.json, checklist.json,
summary.md). Both ask for confirmation first. The repository also ships helper scripts, which delete
from a .er/ directory in the working tree — repo-local mode:
scripts/er-cleanup-reviews.sh # remove review.json, checklist, summary, …
scripts/er-cleanup-questions.sh # remove questions.json
To remove all Easy Review data and apps from the machine, use
er uninstall or Desktop Settings → Uninstall — see
Installation → Uninstalling.