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

PlatformStorage 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:

FileWritten byPurpose
review.jsonAI Hub: review (TUI “Review work” / desktop “Run review”)Per-file risk levels and inline findings
order.jsonAI Hub: reviewSuggested review order
checklist.jsonAI Hub: reviewReview checklist items
summary.mdAI Hub: reviewMarkdown summary of changes
triage.jsonAI Hub: Triage branchFast branch scan / routing
professor.jsonAI Hub: ProfessorTeaching / learning insights
experts/*.jsonAI Hub: Specialized reviewDomain-specific expert findings
tour.jsonAI Hub: Generate guided tour (TUI “Generate guided tour” / desktop “Generate tour”)Guided-tour pillars and file order
diagrams/*.jsonAI Hub: Diagrams (desktop Context tab)Mermaid diagrams of the diff (mental model, subsystems, flows, or custom)
questions.jsoner (q)Personal review questions
notes.jsoner (draft type cycled with Ctrl+t)Local actionable notes for agent hand-off
github-comments.jsoner (c)GitHub PR comments
session.jsonerSession metadata
reviewederPer-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.