Core Concepts
How er Works
Everything in this section applies to both the terminal and desktop apps — they share one review engine. This page is the mental model; the pages that follow drill into each piece.
The core idea
Most diff tools assume you wrote the code and just want to look at it before committing. er
assumes an AI assistant may have written a lot of it, that the diff keeps changing while you read, and that
review is now the bottleneck. So it optimizes for three things: speed (instant startup, keyboard
navigation), liveness (the diff updates itself as code changes), and a feedback loop
with whatever AI tools you already use.
It shells out to git
er does not reimplement git. It runs git diff and friends and parses the unified diff
output into a structured model: each file contains hunks, and each hunk contains
lines. Diff output is always fetched with --no-color and --no-ext-diff,
so external diff tools like difftastic or delta never interfere. Because git is always installed and battle-tested,
this handles every edge case for free.
Base branch is detected for you
When you open the branch diff, er needs to know what to compare against. It works down a fallback chain:
- Your branch's upstream tracking branch, if set.
mainmasterdevelopdev
You never have to pass a base branch. When the gh CLI is available and your branch has an open pull
request that targets a different base, er shows a hint — it does not silently switch on you.
Watch mode keeps the diff live
A file-system watcher runs from launch. It monitors three things at once: your working tree (edits),
.git/index (staging), and .git/refs/ (commits). Changes are debounced — roughly half a
second — so a burst of saves becomes a single refresh. The result: leave er open beside your AI
assistant and the diff simply follows along. This is a core feature, not a toggle you have to discover; it is on
by default.
One consequence worth knowing: when a file's diff content actually changes, er
auto-unmarks it as reviewed. Stale “reviewed” state can never hide new changes from you.
Review tracking is first-class
A review is a stateful activity, not a one-shot glance. er remembers which files you have marked
reviewed, lets you filter to what remains, and can jump you to the next unreviewed file. That state persists
between sessions, keyed to the repository, branch, and view, so a long review survives closing the app. See
Reviewing & Navigation.
Private notes vs. public comments
er deliberately separates your private stream — questions (things you want
answered) and notes (instructions to hand to an agent), both kept local — from
GitHub comments (PR discussion that syncs upstream). They use different colors and are stored
in different files, so you never accidentally publish a private thought. All of them anchor to an exact line
and follow it as the code shifts. Details in Comments & Questions.
The AI loop reads sidecar files
This is the part that makes er more than a diff viewer, so it is worth being precise:
er does not run any AI model. Instead, AI tools you use (the included Claude Code
skills, or the agent spawns built into either app) write structured sidecar files — risk levels,
findings, a checklist, a summary. er reads those files and renders them inline. The loop looks like this:
you / AI Hub er
──────────── ──
AI Hub: run a review ──writes──> review.json, checklist.json, …
(TUI "Review work" / reads & renders findings inline
desktop "Run review")
press q to ask ──writes──> questions.json
AI Hub: Answer questions (TUI only) ──reads───> responds, updates files
refreshes, shows answers inline
publish (TUI Git hub / desktop Push to GitHub) ──> posts review to your GitHub PR
Each sidecar records a SHA-256 hash of the diff it was generated against. When the underlying diff changes, that AI data is dimmed with a stale warning, so you always know whether the analysis still matches the code. Full details in AI Review and Review Storage.
The terminal and desktop apps share everything
Both front ends are thin shells over the same engine (er-engine). They read and write the same review
data, keyed per repository, branch, and view. You can run a review in the desktop app and pick it up in the
terminal, or vice versa — the reviewed marks, questions, comments, and AI artifacts are the same files underneath.
By default those files live in managed application data, not in your repository; see
Review Storage.
No backend, no telemetry
There is no server, no database, and no telemetry — nothing phones home. The only outbound requests
er makes itself are the desktop app's version check against GitHub Releases and the proxy behind its
embedded browser, which fetches the pages you load in it. Otherwise it talks to your local git,
optionally to gh for pull request features, and reads files written by AI tools you control. Your
code never leaves your machine because of er.
With the model in hand, the rest of Core Concepts is a tour of each capability. Start with Diff Modes.