# Problem Addressed > Plannotator is an interactive plan review tool for AI coding agents that intercepts agent plans via hooks, displays them in a visual browser-based UI for annotation, and sends structured feedback back to the agent. - Skill: `tools-only/problem-addressed-37` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add tools-only/problem-addressed-37` - Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/problem-addressed-37/raw - Safety review: pending (external: skill-scanner WARNING, skillspector WARNING) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tools-only (https://skillmd.com/u/tools-only) - Updated: 2026-09-29 - Page: https://skillmd.com/skills/tools-only/problem-addressed-37 --- # Plannotator | Field | Value | | ------------- | ----------------------------------------------- | | Research Date | 2026-01-31 | | Primary URL | | | GitHub | | | Version | No formal releases (monorepo, continuous dev) | | License | BSL 1.1 (Business Source License) | | Created | 2025-12-28 | --- ## Overview Plannotator is an interactive plan review tool for AI coding agents that intercepts agent plans via hooks, displays them in a visual browser-based UI for annotation, and sends structured feedback back to the agent. It supports Claude Code and OpenCode with built-in integrations for Obsidian and Bear Notes for plan archival. The tool also provides code review functionality for git diffs with inline annotations. --- ## Problem Addressed | Problem | Solution | | ------------------------------------------------------ | --------------------------------------------------------------------------- | | AI agent plans are text-only, hard to review | Visual browser-based UI with markdown rendering and syntax highlighting | | No structured way to provide plan feedback | Annotation system: delete, insert, replace, comment operations | | Plans disappear after execution | Obsidian and Bear Notes integration for automatic plan archival | | Team collaboration on agent plans difficult | URL sharing via compressed hash for shareable annotations | | Code review feedback to agents is unstructured | Dedicated code review mode with diff viewer and inline annotations | | Remote development complicates plan review | Environment variables for remote/devcontainer support with port forwarding | | Agent proceeds without human approval | Hook intercepts ExitPlanMode, requires explicit approve/deny action | | Feedback to agent lacks context | Image attachment support with pen, arrow, circle annotation tools | --- ## Key Statistics | Metric | Value | Date Gathered | | ---------------- | ------------------------ | ------------- | | GitHub Stars | 1,538 | 2026-01-31 | | GitHub Forks | 97 | 2026-01-31 | | Open Issues | 30 | 2026-01-31 | | Contributors | 11 | 2026-01-31 | | Primary Language | TypeScript | 2026-01-31 | | Repository Size | 25.6 MB | 2026-01-31 | | Repository Age | 35 days (since Dec 2025) | 2026-01-31 | --- ## Key Features ### Plan Review System - **Hook Integration**: Intercepts Claude Code `ExitPlanMode` permission request via configurable hooks - **Visual Plan Display**: Markdown rendering with syntax-highlighted code blocks - **Annotation Types**: Deletion, insertion, replacement, comment, global comment - **Redline Mode**: Quick text selection creates deletion annotations - **Approve/Deny Flow**: Explicit user action required before agent proceeds ### Code Review System (Jan 2026) - **Git Diff Viewer**: Reviews unstaged changes with multiple diff view modes - **Inline Annotations**: Select line numbers to add annotations - **View Modes**: Switch between unified, split, and raw diff views - **Feedback Submission**: Structured feedback sent to agent session ### Image Annotations - **Image Attachment**: Attach images with feedback - **Drawing Tools**: Pen, arrow, circle tools for visual markup - **Upload Support**: Server-side image handling for agent context ### Note-Taking Integration - **Obsidian Integration**: Auto-save approved plans with YAML frontmatter - **Bear Notes Integration**: Alternative note-taking app support - **Smart Tagging**: Automatic tag extraction from plan title and code languages - **Backlinks**: Graph connectivity via `[[Plannotator Plans]]` reference ### URL Sharing - **Compression Pipeline**: JSON -> deflate-raw -> base64 -> URL-safe encoding - **Full State Sharing**: Shares plan content and all annotations via URL hash - **Position Restoration**: Finds text positions in DOM to restore highlights - **Team Collaboration**: Share annotated plans without server persistence ### Remote Development Support - **Environment Variables**: `PLANNOTATOR_REMOTE`, `PLANNOTATOR_PORT`, `PLANNOTATOR_BROWSER` - **Fixed Port Mode**: Enables port forwarding for devcontainers, SSH, WSL - **Manual URL Mode**: Skips auto-browser-open for remote access --- ## Technical Architecture ### Stack Components | Component | Technology | | ------------------ | --------------------------------------- | | Runtime | Bun | | Language | TypeScript | | UI Framework | React | | Syntax Highlighting| highlight.js (bundled) | | Text Highlighting | web-highlighter library | | Build Tool | Vite (single-file HTML output) | | Compression | CompressionStream API (deflate-raw) | ### Monorepo Structure ```text plannotator/ ├── apps/ │ ├── hook/ # Claude Code plugin │ │ ├── .claude-plugin/ # Plugin manifest │ │ ├── commands/ # Slash commands (plannotator-review.md) │ │ ├── hooks/ # PermissionRequest hook config │ │ └── server/ # Entry point (plan + review subcommands) │ ├── opencode-plugin/ # OpenCode integration │ ├── review/ # Standalone review server │ ├── portal/ # Shared plan viewer (share.plannotator.ai) │ └── marketing/ # Marketing site (plannotator.ai) ├── packages/ │ ├── server/ # Shared server implementation │ ├── ui/ # Shared React components │ ├── editor/ # Plan review App.tsx │ └── review-editor/ # Code review UI └── .claude-plugin/ # Marketplace registration ``` ### Hook Flow ```text Claude calls ExitPlanMode | PermissionRequest hook fires | Bun server reads plan from stdin JSON (tool_input.plan) | Server starts on random port, opens browser | User reviews plan, adds annotations | Approve -> stdout: {"hookSpecificOutput":{"decision":{"behavior":"allow"}}} Deny -> stdout: {"hookSpecificOutput":{"decision":{"behavior":"deny","message":"..."}}} ``` ### Server API Endpoints **Plan Server**: | Endpoint | Method | Purpose | | ---------------------- | ------ | ---------------------------------------------- | | `/api/plan` | GET | Returns plan content and origin | | `/api/approve` | POST | Approve plan with save options | | `/api/deny` | POST | Deny plan with structured feedback | | `/api/image` | GET | Serve uploaded images | | `/api/upload` | POST | Upload image for annotation | | `/api/obsidian/vaults` | GET | Detect available Obsidian vaults | **Review Server**: | Endpoint | Method | Purpose | | -------------- | ------ | ------------------------------------ | | `/api/diff` | GET | Returns raw patch and git ref | | `/api/feedback`| POST | Submit review with annotations | ### Data Types ```typescript enum AnnotationType { DELETION = "DELETION", INSERTION = "INSERTION", REPLACEMENT = "REPLACEMENT", COMMENT = "COMMENT", GLOBAL_COMMENT = "GLOBAL_COMMENT", } interface Annotation { id: string; blockId: string; startOffset: number; endOffset: number; type: AnnotationType; text?: string; originalText: string; createdAt: number; author?: string; } interface Block { id: string; type: "paragraph" | "heading" | "blockquote" | "list-item" | "code" | "hr"; content: string; level?: number; language?: string; order: number; startLine: number; } ``` --- ## Installation and Usage ### Prerequisites Install the `plannotator` command: ```bash # macOS / Linux / WSL curl -fsSL https://plannotator.ai/install.sh | bash # Windows PowerShell irm https://plannotator.ai/install.ps1 | iex ``` ### Claude Code Plugin Installation ```text /plugin marketplace add backnotprop/plannotator /plugin install plannotator@plannotator ``` Restart Claude Code after plugin install. ### Manual Hook Installation Add to `~/.claude/settings.json`: ```json { "hooks": { "PermissionRequest": [ { "matcher": "ExitPlanMode", "hooks": [ { "type": "command", "command": "plannotator", "timeout": 1800 } ] } ] } } ``` ### OpenCode Installation Add to `opencode.json`: ```json { "plugin": ["@plannotator/opencode@latest"] } ``` ### Environment Variables | Variable | Description | | -------------------- | -------------------------------------------------- | | `PLANNOTATOR_REMOTE` | Set to `1` for remote mode (fixed port, no auto-open) | | `PLANNOTATOR_PORT` | Fixed port (default: random locally, 19432 remote) | | `PLANNOTATOR_BROWSER`| Custom browser path | ### Code Review Usage ```text /plannotator-review ``` Opens diff viewer for unstaged git changes with annotation support. --- ## Relevance to Claude Code Development ### Direct Applications 1. **Hook System Reference**: Demonstrates production use of Claude Code's `PermissionRequest` hook system for `ExitPlanMode` interception. 2. **Plugin Marketplace Pattern**: Shows complete plugin structure with marketplace.json registration, commands, and hooks configuration. 3. **Plan Feedback Loop**: Establishes a pattern for structured human-in-the-loop plan review before implementation. 4. **Visual Plan Review UX**: Proves value of visual annotation over text-only plan feedback. 5. **Single-File HTML Deployment**: Vite build produces self-contained HTML files for easy hook integration. ### Patterns Worth Adopting 1. **Annotation Type System**: The DELETE/INSERT/REPLACE/COMMENT taxonomy provides structured feedback categories beyond free-text comments. 2. **URL Hash State Sharing**: Compressed state in URL hash enables stateless sharing without server persistence. 3. **Dual-Mode Review**: Separate plan review and code review workflows for different feedback contexts. 4. **Note Integration**: Automatic archival to knowledge management tools (Obsidian) creates searchable execution history. 5. **Remote Session Detection**: Environment variable flags for remote/devcontainer mode is a clean pattern for deployment flexibility. 6. **Block-Based Parsing**: Markdown-to-blocks parsing enables precise annotation positioning. 7. **Cookie Settings**: Using cookies instead of localStorage allows settings persistence across random ports. ### Integration Opportunities 1. **Native Plan Review**: Plannotator's annotation system could inform Claude Code's native plan review UX. 2. **Hook Library**: The hook configuration patterns are reusable for other PermissionRequest interceptions. 3. **Structured Feedback Format**: The annotation export format (`exportDiff`) could become a standard for plan feedback. 4. **Knowledge Integration**: Obsidian/Bear integration pattern applicable to any execution logging. ### Comparison with Native Claude Code | Aspect | Plannotator | Native Claude Code | | ---------------- | -------------------------------- | ----------------------------- | | Plan Review | Visual browser UI with annotations | Text-based inline editing | | Feedback Format | Structured annotations | Free-text | | Archival | Obsidian/Bear auto-save | Manual copy | | Collaboration | URL sharing | Session-based | | Code Review | Dedicated diff viewer | Inline in conversation | | Remote Support | Environment variable flags | Native terminal | | Setup Required | Plugin install + restart | None | --- ## References | Source | URL | Accessed | | ---------------------- | ------------------------------------------------------ | ---------- | | Official Website | | 2026-01-31 | | GitHub Repository | | 2026-01-31 | | GitHub README | | 2026-01-31 | | GitHub CLAUDE.md | | 2026-01-31 | | Hook Installation Docs | | 2026-01-31 | | GitHub API | | 2026-01-31 | | LICENSE File | | 2026-01-31 | | Claude Code Demo | | 2026-01-31 | | OpenCode Demo | | 2026-01-31 | **Research Method**: Information gathered from official GitHub repository via GitHub API, README and CLAUDE.md files fetched directly, LICENSE file reviewed for licensing terms. Statistics verified via direct API calls on research date. --- ## Freshness Tracking | Field | Value | | ------------------ | ---------------------------------- | | Version Documented | No formal releases (monorepo) | | Last Push | 2026-01-29 | | GitHub Stars | 1,538 (as of 2026-01-31) | | GitHub Forks | 97 (as of 2026-01-31) | | Next Review Date | 2026-05-01 | **Review Triggers**: - First formal version release - Significant star growth (5K, 10K milestones) - New agent platform integrations beyond Claude Code and OpenCode - Major annotation system changes - New collaboration features (real-time sync, commenting) - Changes to hook system or plugin structure - BSL license change date (2030-01-01 conversion to open source) - Breaking changes to API endpoints - Native Claude Code plan review feature release (competitive context)