Problem Addressed

Plannotator

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

Key Statistics

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

Monorepo Structure

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

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:

Review Server:

Data Types

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:

# macOS / Linux / WSL
curl -fsSL https://plannotator.ai/install.sh | bash

# Windows PowerShell
irm https://plannotator.ai/install.ps1 | iex

Claude Code Plugin Installation

/plugin marketplace add backnotprop/plannotator
/plugin install plannotator@plannotator

Restart Claude Code after plugin install.

Manual Hook Installation

Add to ~/.claude/settings.json:

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "plannotator",
            "timeout": 1800
          }
        ]
      }
    ]
  }
}

OpenCode Installation

Add to opencode.json:

{
  "plugin": ["@plannotator/opencode@latest"]
}

Environment Variables

Code Review Usage

/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

References

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

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)