Core Concepts
AI Review
This is what er is named for. It does not run AI itself — it reads structured review
artifacts that AI tools you run write to disk, and renders them inline against the diff. This page explains the
loop, the artifacts, and the agents that produce them.
er is a viewer and orchestrator, not a model. No code is sent anywhere by
er. You bring your own AI tool (Claude Code, Codex, Cursor, …) and credentials; you are the customer of
those providers and responsible for their terms of use.
Running a review: the AI Hub
Both apps have a built-in AI Hub that spawns the review agents for you — no second terminal required. Open it with a in the terminal app or Cmd+K → AI in the desktop app, then choose an action: a full review, a single expert, the professor, a fast triage, answering your questions, or a summary. The Hub runs your AI tool as a subprocess and writes the same sidecar artifacts described below, which then render inline against the diff.
The Hub drives your AI CLI — it does not bundle a model. It defaults to
Claude Code (the claude command on your PATH); point it at Codex,
Cursor, or another tool through the [agent] / [ai_hub] config. See
Configuration → AI Hub for providers and model selection, and
Desktop Features for the desktop Hub, review queue, and Arena.
Reviews you run from the Hub write to where the app reads automatically. See Review Storage for the full sidecar layout.
The review loop
Open the AI Hub and work through the review without leaving the app.
| Step | Where | What happens |
|---|---|---|
| 1 | AI Hub | Open the Hub (Cmd+K → AI, or a) and choose Run review (TUI: Review work). The agents analyze the diff and write sidecar files. |
| 2 | er | Detects the new files automatically; findings appear inline (toggle the layer with A in the TUI). |
| 3 | er | You read findings, leave questions with q, comments with c. |
| 4 | AI Hub | TUI: open the Hub and choose Answer questions (enabled once you have added a question). Desktop: questions are managed in the Notes panel — each has its own AI actions. |
| 5 | er | Auto-refreshes; AI responses appear inline. Continue reviewing. |
| 6 | er | Publish to GitHub: TUI open the Git hub (g) → Push comments to GitHub. Desktop: use the Comments card Push to GitHub → "Push as review" or push individual comments. |
What a review produces
A full review writes several sidecar files. er reads them and turns them into UI:
| File | Becomes |
|---|---|
review.json | Per-file risk levels (high / medium / low / info) in the file list, plus inline findings in the diff. |
order.json | Not shown in the UI. The file names an intended reading order; a hash mismatch only marks the review stale. |
checklist.json | A verification checklist of things to confirm. |
summary.md | A markdown summary of the change. |
Findings render as inline banners attached to the relevant lines, color-coded by the agent that produced them. See Review Storage for the complete file list and where it lives on disk.
Result<()> lets the caller decide how to handle failure — see the error-handling chapter.Severity model
All the review agents share one severity scale and a “what not to flag” list:
| Level | Meaning |
|---|---|
| P0 — high | Must fix. |
| P1 — medium | Should fix. |
| P2 — low | Nice to fix. |
| info | Observation only. |
By design the agents never flag naming, formatting, style, or pure file moves — that noise is what makes AI review tiring. Summaries and checklists focus on P0/P1.
Expert agents
Beyond the general review, specialized expert agents look at one dimension each and write only to
experts/<id>.json — they never overwrite the general artifacts. When their output matches the
current diff hash, er merges their findings in as additional inline banners, each labeled with the
expert's name.
| Expert | Focus |
|---|---|
security | Security issues |
performance | Performance |
reliability | Reliability / robustness |
testing | Test coverage and quality |
api | API design and contracts |
patterns | Pattern consistency with the codebase |
simplifying | Readability and complexity |
mentorship | Exemplary patterns worth reinforcing |
The professor
The Professor is not a code review — it is a learning agent. Open the AI Hub (Cmd+K → AI, or a)
and choose Professor (TUI: Professor; Desktop: Professor, which opens an
optional focus-prompt modal). It writes teaching insights to professor.json, merged inline and labeled
with a Professor pill. Use it to understand why a change is shaped the way it is, rather
than to find defects.
Triage
Triage is a fast first pass. Open the AI Hub and choose Triage branch (same label in both apps):
a quick branch scan that produces a first impression, a routing verdict (run a general review? an expert? skip deep
review?), and a priority file list, written to triage.json. It is the cheapest way to decide how much
review a branch actually warrants.
Dialing AI context up and down terminal
In the terminal, inline AI findings are a toggleable layer: A shows or hides them (comments and questions have their own layers on C and Q, and X hides resolved items). The right-hand context panel cycles with p / P through file details, the AI summary with the risk breakdown, the PR overview, and the agent log. Together they let you move from a plain diff to a fully annotated one without leaving the keyboard. In the desktop app the equivalent switches live in the diff toolbar and right panel.
Staleness
Every sidecar records the SHA-256 hash of the diff it was generated against. When the diff changes — which happens constantly in watch mode — any AI data whose hash no longer matches is dimmed with a stale warning. You are never misled into trusting analysis of code that has since changed. Re-run the relevant action from the AI Hub to refresh it.
Choosing a model: the AI Hub
er can drive different providers and models. The [agent] config sets a single default
command; the optional [ai_hub] config defines presets (Claude, Codex, Cursor, OpenCode and their models) you can
switch between at runtime without editing config mid-session. The same provider, model, and reasoning effort
apply to every Hub action. The full schema is in
Configuration → AI Hub.
Trying it without an AI tool
To explore how the overlays render without running a real review, generate sample artifacts:
cd your-repo
bash /path/to/easy-review/scripts/generate-test-fixtures.sh
ER_REPO_LOCAL=1 er # read sidecars from the repo's .er/ directory
The script writes repo-local .er/ files with a matching diff hash, so run er with
ER_REPO_LOCAL=1 (see Review Storage) and the AI views light up against
your current diff.
The full catalog of AI Hub Actions — what each one runs and what it writes — is on the AI Hub Actions page.