pi-annotate

A visual annotation extension for pi-agent that opens an interactive annotation UI for reviewing context messages and markdown documents. On macOS, uses Glimpse to render in a native WKWebView window; falls back to a browser tab on other platforms.

Installation

pi install npm:@jackice/pi-annotate

Or install from a local path:

pi install /path/to/pi-annotate

Restart pi or run /reload to load the extension.

Requirements:

• pi-agent v0.35.0 or later (extensions API)
• For native macOS window: npm install -g glimpseui@">=0.8.1" (optional, falls back to browser if not installed) — Glimpse 0.8.1+ required for native clipboard support (⌘C/⌘V)

Features

• Message Annotation: Annotate the last assistant message with visual feedback — select text, add comments, and send feedback to the agent
• Document Annotation: Open any markdown file (specs, plans, design docs) in a visual annotation UI
• Auto-Detect: Opens the annotation UI after the agent creates or modifies a document matching include (default docs/superpowers/**/*.md), once the agent run settles
• Annotation Types: Comment, Suggestion, Issue, and Praise — each with distinct color coding
• Quick Labels: One-click preset labels for common feedback (needs clarification, missing details, verify assumption, etc.)
• Floating Toolbar: Select text to reveal a compact toolbar with Comment, Delete, Quick Label, and Looks Good actions
• Inline Comment Popup: Click Comment on the toolbar to add detailed text feedback directly above/below the selected text
• Feedback Delivery: Annotations are sent back to the agent as a structured follow-up message
• Approve Without Feedback: When no annotations exist, approve documents directly
• Theme Toggle: Switch between dark and light themes with ⌘+Shift+L (Ctrl+Shift+L off macOS)
• Auto-Close: Window closes automatically after submitting feedback or approving

How It Works

┌─────────┐     ┌──────────────────────────────────────┐     ┌─────────┐
│  Agent  │     │     Glimpse / Browser Annotation UI   │     │  Agent  │
│ writes  ├────►│                                      ├────►│receives │
│  doc    │     │  select text → add annotation → send  │     │feedback │
└─────────┘     │         ↑                             │     └─────────┘
                │         └── write/edit trigger ────────┤
                └──────────────────────────────────────┘

Lifecycle:

1. Agent writes a spec/plan document, or you run /annotate <file> or /annotate-last
2. Local server starts → Glimpse window opens (macOS) or browser tab (elsewhere)
3. Select text in the document → floating toolbar appears with annotation actions
4. Add annotations via Comment (text input), Quick Label (preset labels), Delete (suggest removal), or Praise (looks good)
5. Session ends via:
   • Send Feedback → annotations sent back to agent as follow-up message
   • Approve → document approved, no feedback sent (available when no annotations exist)
   • Close window → session ends without feedback
6. Window closes automatically after sending feedback or approving

Workflow document reviews

Approval, feedback, and exit requests require the current session token and same origin. Failed document loading disables decisions. Closing a workflow review dismisses that request; an accepted approval wakes the main agent once. Tests use npm test (Node.js).

When workflow-mode is loaded in the same Pi session, it can open this UI for a version-bound spec, plan, outline, or draft review. The workflow records and validates the decision before the UI reports success. Approving a workflow plan grants implementation approval only for that plan and its bound spec version. Ordinary /annotate, /annotate-last, and automatic annotations remain independent and do not grant workflow approval.

Usage

The extension provides two slash commands and a write/edit-based auto-annotation hook:

/annotate-last

Annotate the last assistant message in the current session:

/annotate-last

Select text in the message, add annotations or quick labels, and send feedback to the agent.

/annotate <file>

Annotate a specific markdown file:

/annotate docs/superpowers/specs/my-design.md
/annotate PLAN.md

Supports:

• Relative paths (from current working directory)
• Absolute paths
• @ prefix notation (e.g., @docs/superpowers/specs/...)

Auto-Detect

The extension listens to write and edit tool calls. When the agent writes or modifies a markdown file matching include, the annotation UI opens after the agent run settles (agent_settled). Reading a document or mentioning its path in a response never triggers it. Auto-open does not block the session; feedback is delivered as a follow-up message.

• The same file opens at most once per content version; closing the window mutes it for the rest of the session.
• Only newly created files open by default; set autoOpen to "write" to include modifications, or "off" to disable.

Configuration

pi-annotate reads its own config file (pi's settings.json schema has no extension section):

1. Global: ~/.pi/agent/annotate.json
2. Project: <project>/.pi/annotate.json (overrides global)
3. Environment: PI_ANNOTATE_AUTO=off|create|write

{
  "autoOpen": "create",
  "include": ["docs/superpowers/**/*.md"],
  "onWindowClose": "mute"
}

Annotation UI

Floating Toolbar

Select any text to reveal a floating toolbar with four actions:

Quick Labels

Preset labels for common feedback on specs, plans, and messages:

Annotation Panel

All annotations appear in the right sidebar panel. Each annotation shows:

• Type badge with color coding (Comment/Suggestion/Issue/Praise)
• Annotation text
• Original selected text preview
• Timestamp
• Edit (✏️) and Delete (🗑️) buttons

Keyboard Shortcuts

File Structure

pi-annotate/
├── index.ts              # Extension entry point, commands, Glimpse integration
├── auto-annotate.ts      # Auto-open trigger, config, de-duplication
├── server.ts              # Annotation HTTP server (API routes)
├── form/
│   └── annotate.html      # Annotation UI (pure HTML/CSS/JS, no build step)
├── package.json
└── README.md

Feedback Format

When you send feedback, the agent receives a structured message like:

## Annotation Feedback

The following feedback was provided for docs/superpowers/specs/my-design.md:

- **suggestion**: Consider adding concrete API design details
  > Original text: "Communication uses a RESTful API"

- **issue**: Error handling strategy is missing
  > Original text: "The system will return an error message on failure"

Please address the issues above.

The ending is context-aware:

• If there are issues: "Please address the issues above."
• If there are suggestions: "Please revise according to the suggestions above."
• Otherwise: "Please consider the feedback above."

Limits

• Max 5MB request body for feedback submission
• 2-minute idle timeout auto-closes the server
• Single concurrent annotation session