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 ● | |
|---|---|---|---|
| Color | Yellow | Yellow, with a 📝 icon | Cyan |
| Intent | Something you want answered | An instruction to hand to an agent | Feedback for your team on the PR |
| Stored in | questions.json | notes.json | github-comments.json |
| Replies? | Yes — local replies, never pushed | Yes — local replies, never pushed | Yes — single-level threads |
| Synced upstream? | Never — stays local | Never — stays local | Yes, 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:
| Key | Action |
|---|---|
| q | Start a question on the current line |
| c | Start a GitHub comment on the current line (in Staged mode c starts a commit instead) |
| Ctrl+t | While composing: cycle the draft type — question → note → comment |
| Q / C | Toggle 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.
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:
| Key | Action |
|---|---|
| J / K | Focus the previous / next comment, question or note |
| r | Reply to the focused comment or finding |
| e | Edit the focused comment (your own, top-level) |
| x | Delete the focused comment (with confirmation) |
| X | Hide / 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:
| Key | Action |
|---|---|
| G | Pull review comments from GitHub into your diff |
| g → Push comments to GitHub | Push 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.