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.

Annotation UI: select text to reveal a floating toolbar, annotations appear in the right panel

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)

• 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: Automatically detects new spec/plan documents in docs/superpowers/specs/ or docs/superpowers/plans/ and opens the annotation UI
• 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

┌─────────┐     ┌──────────────────────────────────────┐     ┌─────────┐
│  Agent  │     │     Glimpse / Browser Annotation UI   │     │  Agent  │
│ writes  ├────►│                                      ├────►│receives │
│  doc    │     │  select text → add annotation → send  │     │feedback │
└─────────┘     │         ↑                             │     └─────────┘
                │         └── auto-detect path ─────────┤
                └──────────────────────────────────────┘

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

The extension provides two slash commands and one auto-detection hook:

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 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/...)

When an agent creates or modifies a file under docs/superpowers/specs/ or docs/superpowers/plans/, the extension automatically detects the file path in the assistant's response and opens the annotation UI.

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

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

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

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

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."

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