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.

StepWhereWhat happens
1AI HubOpen the Hub (Cmd+K → AI, or a) and choose Run review (TUI: Review work). The agents analyze the diff and write sidecar files.
2erDetects the new files automatically; findings appear inline (toggle the layer with A in the TUI).
3erYou read findings, leave questions with q, comments with c.
4AI HubTUI: 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.
5erAuto-refreshes; AI responses appear inline. Continue reviewing.
6erPublish 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:

FileBecomes
review.jsonPer-file risk levels (high / medium / low / info) in the file list, plus inline findings in the diff.
order.jsonNot shown in the UI. The file names an intended reading order; a hash mismatch only marks the review stale.
checklist.jsonA verification checklist of things to confirm.
summary.mdA 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.

er — AI review ⚠ 3 findings
src/auth/token.rsA · AI findings ON
14− fn verify(t: Token) -> bool {
14+ async fn verify(t: Token) -> Result<()> {
⚠ SecurityP0 · high
Expiry is never checked — an expired token still verifies.
15+ self.store.save(&t).await?;
⚠ PerformanceP2 · low
Blocking store write on the hot path — consider batching.
16 Ok(())
🎓 Professorteaching
Result<()> lets the caller decide how to handle failure — see the error-handling chapter.
AI summary
Risk · High
Findings · 3
●1 · P0 high
●1 · P2 low
●1 · professor
Experts run
securityperformance
Checklist
✓Error handling
○Token expiry
○Tests
Findings appear as inline banners on the lines they touch — color-coded by agent (Security/Performance in orange, Professor in blue) — beside an AI summary panel with the risk rating, finding counts, and checklist. Toggle the findings layer with A and cycle the panel with p to dial how much of this is shown.

Severity model

All the review agents share one severity scale and a “what not to flag” list:

LevelMeaning
P0 — highMust fix.
P1 — mediumShould fix.
P2 — lowNice to fix.
infoObservation 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.

ExpertFocus
securitySecurity issues
performancePerformance
reliabilityReliability / robustness
testingTest coverage and quality
apiAPI design and contracts
patternsPattern consistency with the codebase
simplifyingReadability and complexity
mentorshipExemplary 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.