pi-annotations

Review long pi responses the way you review a PR: mark the exact lines you have opinions about, attach a note to each, and send them all as one batch. Each note arrives with the verbatim passage it refers to, so the agent never has to guess what "that part" means.

Why

Agents in planning and discovery phases emit long, structured output. Replying to five different parts of it today means writing one giant synthesized message or five serial round trips. This extension adds a third option: an annotation overlay where you mark spans and jot notes as you read, then deliver everything at once.

Install

pi install npm:pi-annotations
# or straight from git:
pi install git:github.com/patelparth3/pi-annotations@v1.0.0

Try it without installing:

pi -e npm:pi-annotations

Usage

Run /annotate (or press ctrl+shift+a) any time after the agent replies. The last assistant message opens in a review overlay.

Mode	Keys
Navigate	j/k/arrows, PgUp/PgDn, g/G
Mark	v start/extend a span, s/enter confirm it
Note	i/a/enter on a line: add a note, or edit the existing one
Note input	enter save, esc discard; saving an emptied note deletes the annotation
Batch	x/d delete under cursor, C clear all, shift+enter/S send, esc close

Closing the overlay without sending keeps your work as a draft: reopening on the same message restores every annotation and the cursor position. Sending clears the draft.

The batch arrives as a single user message with each note anchored to its quoted passage:

2 comment(s) on your last message - each quote anchors the comment below it. Address each by number and flag any conflicts.

[1]
> Store sessions in Redis with a 24h TTL and refresh the expiry on every request.
Note: refreshing on read means idle users never time out - is that intended?

[2]
> Delete the legacy /v1/auth endpoint once the migration ships.
Note: keep it behind a flag for one release instead of deleting outright

If the agent is still running when you send, the batch is queued as a follow-up automatically.

Terminal notes

ctrl+shift+a and shift+enter rely on the Kitty keyboard protocol, which pi negotiates automatically on terminals that support it (Ghostty, kitty, WezTerm). On other terminals the trigger chord degrades harmlessly to plain ctrl+a, and S remains as the always-working send key. /annotate works everywhere regardless.

Configuration

PI_ANNOTATE_SHORTCUT overrides the trigger chord:

PI_ANNOTATE_SHORTCUT=f2 pi

Design

Annotations anchor to content, not position: what gets quoted is the exact source text of the lines you marked, never line numbers. Rendered wrapping is display-only and cannot corrupt the anchor text. The whole batch is delivered as one message so the agent sees every note while addressing each one - and one review round costs a single turn, not five. Quotes are anchors rather than payloads: spans longer than a few lines are truncated to their edges, since the agent already has the full text in context.

Development

npm install
npm test

The test suite drives the overlay headlessly through jiti - no terminal required.