Plannotator

Plannotator is a plan review UI designed for Claude Code that intercepts ExitPlanMode via hooks. It provides an interactive browser-based interface to review plans, select text for annotations, and provide structured feedback such as deletions, comments, global comments, quick labels, and "looks good" approvals.

Key Capabilities:

• Plan Review: Intercepts ExitPlanMode to open a rich annotation UI.
• Code Review: Review uncommitted changes using a diff viewer.
• Markdown Annotation: Annotate any markdown file.
• Sharing: Share plans and annotations via URL without requiring a backend.
• Obsidian Integration: Automatically saves reviewed plans to your Obsidian vault.

When creating any visual content (Plans, PRs, or General), adhere to these core principles:

• Whitespace is a feature: Use generous padding and large section gaps. If content feels cramped, increase space rather than shrinking text.
• One idea per viewport: Structure content so that only one major idea (e.g., a hero section, a diagram, or a detail grid) is prominent at a time.
• Show, don't describe: Use timelines for sequencing, diagrams for relationships, and code blocks for interfaces instead of long prose descriptions.
• No time estimates: Timelines should show phases and dependencies only. Never include hour or day estimates.

Plannotator's review agents (Claude, Codex, and Code Tour) structure their requests using three distinct layers. This ensures that the agentic exploration of the CLI is combined with a machine-readable output format.

1. System prompt: Owned and managed by the underlying CLI (e.g., Claude Code or codex-rs). Plannotator does not modify this.
2. User message: A single concatenated string sent by Plannotator consisting of a static review prompt and a dynamic user prompt, separated by ---.
3. Output schema: A JSON schema passed as a flag to the CLI to force the final assistant response into a specific, machine-readable shape.

The extension manages a state machine that controls agent capabilities.

Default behavior: idle → planning → executing → idle.

With external execution enabled: idle → planning → idle (emits a handoff event).

Capabilities by state:

• Planning: All tools from other extensions remain available. Bash is unrestricted (though the system prompt guides the agent to avoid destructive commands). Writes and edits are restricted to the plan file only.
• Executing: Full tool access is granted (read, bash, edit, write). Progress is tracked using [DONE:n] markers in agent responses. The plan is re-read from disk during every turn to ensure synchronization.

The Agent Terminal feature uses a hybrid runtime model to ensure production reliability:

1. Plannotator (Bun): Acts as the main server and owns the browser-facing API endpoints.
2. Node.js Sidecar: A separate process (agent-terminal-node-sidecar.mjs) that manages the actual PTY. This is necessary because the PTY requires Node.js modules like node-pty and ws which cannot be imported from Bun's virtual filesystem.
3. WebTUI: Provides the terminal behavior and UI logic via @plannotator/webtui.

In production, the Node sidecar runs from a managed directory (typically ~/.plannotator/vendor/agent-terminal/) to ensure all dependencies are available on disk.

You can share plans via room.plannotator.ai.

• Small plans: Encoded in the URL hash (no server involved).
• Large plans: Encrypted with AES-256-GCM and sent via a short-link service. The server only stores ciphertext; the key remains in your URL fragment.

To disable sharing entirely, set the environment variable PLANNOTATOR_SHARE=disabled.

The Guided Review UI is implemented as a layout branch in App.tsx rather than an overlay. To prevent destroying the existing panel/tab layout (which happens if <DockviewReact> is unmounted), the takeover must CSS-hide the dock wrapper and the file tree instead of unmounting them.

Key implementation details:

• The guide is a conditional branch in the main content row in App.tsx (around line 2671).
• Use CSS to hide the dock (e.g., App.tsx:2793) to keep diff-switch epoch guards and draft deduplication decoupled from the guideOpen state.
• The guide surface consumes the single SSE connection from useAgentJobs() via props or context.

To use Plannotator in containerized environments, set the PLANNOTATOR_REMOTE and PLANNOTATOR_PORT environment variables and forward the specified port. If the browser does not open automatically, manually navigate to http://localhost:<PORT> when submit_plan is called.

{
  "containerEnv": {
    "PLANNOTATOR_REMOTE": "1",
    "PLANNOTATOR_PORT": "9999"
  },
  "forwardPorts": [9999]
}