Core Concepts

Comments & Questions

er keeps three separate streams of inline annotations: questions you keep to yourself (and hand to your AI), notes — private instructions framed for hand-off to an agent — and GitHub comments that sync to a pull request. They look different and never get confused with one another — so a private thought can't accidentally end up on a PR.

Why three kinds?

Questions ●Notes 📝GitHub comments ●
ColorYellowYellow, with a 📝 iconCyan
IntentSomething you want answeredAn instruction to hand to an agentFeedback for your team on the PR
Stored inquestions.jsonnotes.jsongithub-comments.json
Replies?Yes — local replies, never pushedYes — local replies, never pushedYes — single-level threads
Synced upstream?Never — stays localNever — stays localYes, two-way via gh

Questions are your scratchpad: “why is this here?”, “does this handle the empty case?”. In the TUI, the AI Hub Answer questions action reads them, answers, and updates the file in place. Notes are the same private, local-only mechanism with a different intent — “rename this before merging”, “add a test for the empty case” — phrased so you can hand them straight to a coding agent. GitHub comments are the things you actually want your team to see on the PR.

In the desktop app, questions and notes share the Notes panel (sub-tabs All | Notes | Questions) with the same actions: resolve, delete, reply, promote to a GitHub comment, and export. Each also has one AI action of its own — a question can be elaborated by the AI, a note can be validated against the current diff. Promoting a question or note to a comment is the deliberate one-way bridge from your private stream into the shared PR space.

Leaving a note

Navigate to a line with the arrow keys (extend a multi-line selection with Shift+↓/↑), then press the matching key to start a draft:

KeyAction
qStart a question on the current line
cStart a GitHub comment on the current line (in Staged mode c starts a commit instead)
Ctrl+tWhile composing: cycle the draft type — question → note → comment
Q / CToggle the visibility of the questions/notes layer and the comments layer

A small input opens at the bottom; type your note and confirm. There is no dedicated key for notes — start a question or comment draft and press Ctrl+t until the draft type reads note. The annotation then renders inline, right after its target line in the diff — not bundled at the end of the hunk — so the conversation sits exactly where the code is.

src/auth/login.rs 💬 3
22+ let token = self.issue_token(&user)?;
💬 @reviewerGitHub · 1h ago
Should we validate the token format before issuing?
↳ @author: good call — added a format check in the next commit
23+ let session = Session::new(user, token);
? private questionlocal only
What happens if the token expires mid-session?
24+ self.store.save(&session).await?;
💬 @bob⚠ stale
Line moved — this comment may be misplaced.
c GitHub comment· q question· r reply· x delete· J/K focus comments
Separate streams, never confused: cyan GitHub comments (with single-level replies) sync to the PR, while yellow private questions and 📝 notes stay local for you and your AI. A comment whose target line vanished is dimmed and marked stale.

Acting on existing comments

To act on existing annotations rather than the diff, focus one with J / K — these jump backward / forward through comments, questions and notes, across files. AI findings are a separate stream and have their own keys: Ctrl+J / Ctrl+K. These actions then apply to the focused item:

KeyAction
J / KFocus the previous / next comment, question or note
rReply to the focused comment or finding
eEdit the focused comment (your own, top-level)
xDelete the focused comment (with confirmation)
XHide / show resolved items

Replies are single-level

All three kinds support a reply thread: a parent comment plus any number of replies. Replies cannot themselves have replies — the model is intentionally flat (parent + children, no recursive nesting) to keep it simple and to match how GitHub PR review threads behave. Replies to a question or a note stay local with their parent and are never pushed; to have the AI answer a question instead of replying yourself, use the AI Hub Answer questions action (TUI) or the per-question AI actions in the desktop Notes panel.

Comments follow the code (and warn when stale)

Every comment stores the content of the line it was attached to. When the diff changes, er tries to re-anchor it to that same line even if it moved. If the target line disappears entirely, the comment is marked stale: it renders dimmed with a warning indicator so you know it may be misplaced and should be revisited. This staleness is tracked per comment, independently of the file-level AI staleness described in AI Review.

Syncing GitHub comments

With the gh CLI configured and a pull request in view, comments sync both directions:

KeyAction
GPull review comments from GitHub into your diff
g → Push comments to GitHubPush your local comments to GitHub — as one review (r) or as individual comments (i)

Each GitHub comment records its source (local or github), the upstream github_id, the author, and whether it has been synced. Pulling deduplicates on the GitHub id, so you can pull repeatedly without creating copies. The full sync flow lives in GitHub & Pull Requests.

✦

Rule of thumb: use q while you are still figuring out whether something is a problem, a note once you know what should change, and c once you are ready to say it out loud on the PR. Publishing — the Git hub's Push comments to GitHub in the TUI, or the desktop Comments card Push to GitHub — includes your GitHub comments when it posts the review.