AI Coding Agent Extension · Multi-Agent Support

PLAN
NOTATOR

Visual plan review and annotation for AI coding agents. Mark up plans in your browser, approve or reject changes, and send structured feedback straight back to the agent — works with Claude Code, Codex, Gemini CLI, OpenCode and more.

Supported Agents
🤖
Claude Code
Plan ✓ Auto Code Review
🔷
Codex CLI
Plan — N/A Code Review
💎
Gemini CLI
Plan ✓ Auto Code Review
🟣
OpenCode
Plan ✓ Auto Code Review
🔧
Copilot CLI
Plan ✓ Auto Code Review
🥧
Pi
Plan ✓ Auto Code Review
00
Overview
Supported Agents

Plannotator integrates with 6 AI coding agents. Click a tab to see its specific install and command details.

🤖
Claude Code
Full support · Plan mode auto · Code review · PR review
Install

Add the plugin inside Claude Code

# 1. Install plannotator binary (PowerShell) irm https://plannotator.ai/install.ps1 | iex # 2. Inside Claude Code session /plugin marketplace add backnotprop/plannotator
/plannotator-review
Visual review of current git diff
/plannotator-review <pr-url>
Review a GitHub Pull Request
/plannotator-annotate <file>
Annotate any markdown file
/plannotator-last
Annotate Claude's last response
Plan Mode

Activates automatically when Claude Code enters plan mode — no extra command needed.

🔷
Codex CLI
Code review only · Plan mode not yet supported · Uses ! prefix
Install

Install the plannotator binary (same as all agents)

# Windows PowerShell irm https://plannotator.ai/install.ps1 | iex
!plannotator review
Visual review of current git diff
!plannotator review <pr-url>
Review a GitHub Pull Request
!plannotator annotate <file>
Annotate any markdown file
!plannotator last
Annotate the last agent message
⚠ Plan Mode

Plan mode is not yet supported in Codex. Only review and annotate commands are available.

💎
Gemini CLI
Full support · Plan mode auto · Requires Gemini CLI 0.36.0+
Install

Install the binary — Gemini auto-detected

# Installer auto-detects Gemini CLI (~/.gemini) irm https://plannotator.ai/install.ps1 | iex
/plan
Enter plan mode — plans open in browser automatically
/plannotator-review
Code review for current changes
/plannotator-review <pr-url>
Review a GitHub Pull Request
/plannotator-annotate <file>
Annotate a markdown file
Requirement

Requires Gemini CLI version 0.36.0 or later. Run gemini --version to check.

🟣
OpenCode
Full support · Plan mode auto · Plugin via opencode.json
Install

Add to opencode.json, then run install script

// Add to your opencode.json { "plugin": ["@plannotator/opencode@latest"] } # Then run install script (clears plugin cache too) irm https://plannotator.ai/install.ps1 | iex
/plannotator-review
Visual review of current changes
/plannotator-review <pr-url>
Review a GitHub Pull Request
Plan Mode
Auto-activates — no command needed
Restart OpenCode
Required after install or plugin cache clear
After Install

Always restart OpenCode after adding the plugin or running the install script to clear cached plugin versions.

🔧
Copilot CLI
Full support · Plan mode via Shift+Tab · Two plugins required
Install

Install binary, then add two plugins in Copilot CLI

irm https://plannotator.ai/install.ps1 | iex # Inside Copilot CLI session /plugin marketplace add backnotprop/plannotator /plugin install plannotator-copilot@plannotator
Plan Mode

Use Shift+Tab inside Copilot CLI to enter plan mode. Plannotator activates automatically.

🥧
Pi
Full support · Plan mode via --plan flag or /plannotator toggle
Install

Install via Pi's own package manager

pi install npm:@plannotator/pi-extension
pi --plan
Start Pi in plan mode
/plannotator
Toggle plan mode during a session
01
Getting Started
Installation
Before you start

Plannotator works with AI coding agent CLIs — not the Claude.ai browser chat. Make sure you have Node.js installed, and the CLI tool for whichever agent you use.

Step 01 — Install Bun (required)

Install the Bun runtime Windows

Plannotator requires Bun as its package manager. Run in PowerShell, then restart your terminal:

powershell -c "irm bun.sh/install.ps1 | iex"
Step 02 — Install Plannotator binary

Install the plannotator command Windows

This installs the plannotator system command used by all supported agents:

irm https://plannotator.ai/install.ps1 | iex
Step 03 — Install your agent CLI

Pick your agent and install it

Install whichever agent(s) you want to use with Plannotator:

# Claude Code npm install -g @anthropic-ai/claude-code # Codex CLI npm install -g @openai/codex # Gemini CLI (requires Gemini CLI 0.36.0+) npm install -g @google/gemini-cli
Step 04 — Register the plugin

Add Plannotator to your agent

See the Supported Agents section above or jump to the specific agent tutorial below for exact registration steps — each agent is slightly different.

✓ Verify Installation

Run plannotator --version in a terminal. If you see a version number, the binary is installed correctly.

02
Everyday Use
Basic Use

The core feature is Plan Review — it activates automatically when your agent enters plan mode.

💬

Ask agent
to plan

→
🌐

Browser
opens

→
✏️

Annotate
the plan

→
✅

Approve or
send feedback

→
🤖

Agent
proceeds

How To — Trigger Plan Mode

Start your agent in a project folder

Navigate to your project and launch the agent, then ask it to plan something:

cd C:\MyProject claude # Then type: Plan how you would refactor the authentication module
How To — Annotate a Plan

Use the visual browser UI

When plan mode activates, your browser opens automatically. You can:

  • 🟡 Highlight sections to add comments
  • 🔴 Delete parts of the plan you don't want
  • 🟢 Insert new instructions or steps
  • 🔵 Replace sections with your own wording
How To — Approve or Reject

Send your decision back to the agent

  • ✅ Approve — agent proceeds with implementation immediately
  • 🔄 Request Changes — annotations sent back as structured feedback, agent revises the plan
03
Power User
Advanced Use
Advanced — Code Review

Review git diffs visually NEW

Open a visual diff of your current uncommitted changes, or review a PR:

# Claude Code / Gemini CLI / OpenCode /plannotator-review /plannotator-review https://github.com/org/repo/pull/123 # Codex CLI (uses ! prefix) !plannotator review !plannotator review https://github.com/org/repo/pull/123
Advanced — Annotate Any File

Annotate any markdown file and send feedback back

# Claude Code / Gemini / OpenCode /plannotator-annotate docs/architecture.md # Codex !plannotator annotate docs/architecture.md
Advanced — Team Sharing

Share plans with colleagues

  • 📎 Small plans — encoded entirely in the URL, nothing stored on any server
  • 🔐 Large plans — AES-256-GCM encrypted before upload, auto-deletes after 7 days
Team Workflow

Share URL with colleague → they annotate it → you import their feedback → send back to the agent.

Advanced — Pin a Specific Version

Lock to a specific version for stability

# Windows PowerShell & ([scriptblock]::Create((irm https://plannotator.ai/install.ps1))) -Version v0.17.10

Every release ships with SHA256 checksum + SLSA provenance (v0.17.2+).

04
Quick Reference
Cheat Sheet

🛠 Install Commands

  • irm bun.sh/install.ps1 | iexInstall Bun runtime
  • irm plannotator.ai/install.ps1 | iexInstall plannotator binary
  • npm i -g @anthropic-ai/claude-codeInstall Claude Code
  • npm i -g @openai/codexInstall Codex CLI
  • plannotator --versionVerify install

⚡ Claude Code Commands

  • /plugin marketplace add backnotprop/plannotatorRegister plugin
  • /plannotator-reviewReview current diff
  • /plannotator-review <url>Review a PR
  • /plannotator-annotate <file>Annotate a file
  • /plannotator-lastAnnotate last message
  • /plannotator-archive🔮 Browse all past decisions

🔷 Codex CLI Commands

  • !plannotator reviewReview current diff
  • !plannotator review <url>Review a PR
  • !plannotator annotate <file>Annotate a file
  • !plannotator lastAnnotate last message

💎 Gemini / 🟣 OpenCode

  • /planGemini: enter plan mode
  • /plannotator-reviewCode review (both)
  • /plannotator-annotate <file>Annotate file (both)
  • pi install npm:@plannotator/pi-extensionPi install
  • /plannotatorPi: toggle plan mode

🎯 Plan Review Actions

  • ApproveAgent proceeds with implementation
  • Request ChangesSend annotations as feedback
  • Highlight → CommentAdd note to a section
  • Select → DeleteRemove a plan section
  • Select → ReplaceRewrite a section
  • Select → InsertAdd a new step

🔧 Advanced

  • -Version vX.Y.ZPin a specific version
  • bun installInstall deps from source
  • bun run build:reviewBuild review app first
  • bun run buildBuild everything
  • plannotator --versionCheck current version

🔮 Hidden CLI Commands

  • plannotator sessionsList active server sessions
  • plannotator sessions --open NReopen closed browser session
  • plannotator sessions --cleanRemove stale session files
  • plannotator archiveBrowse saved plan decisions
  • plannotator improve-contextInvoke custom context hook
  • plannotator copilot-planCopilot CLI plan interception
  • plannotator copilot-lastCopilot CLI last message
  • plannotator --helpFull hidden command list

🏴 Hidden Flags

  • --browser "Firefox"Override browser globally
  • --no-jinaDisable Jina Reader for URLs
  • --no-localSkip local checkout for PR review
  • --localForce local checkout (PR review)

⛔ Rejected / Never Do This

  • npm install❌ Will fail — repo requires Bun (workspace:* protocol)
  • bun run build (first)❌ Silently copies stale HTML — always build:review first
  • plannotator (no args, non-interactive)❌ Reserved for hook JSON on stdin; use review / annotate
  • /plannotator-review in Codex❌ Use ! prefix in Codex, not /
  • /plan in Codex❌ Plan mode not supported in Codex yet
  • Adding JWT/API keys to annotations❌ Annotations are stored in plaintext on disk
  • Sharing plans with secrets❌ Large plans go to share service — encrypt client-side first
  • PLANNOTATOR_PORT=80 / 443❌ Requires root; use 9xxx range instead

🚦 Troubleshooting

ProblemFix
npm error EUNSUPPORTEDPROTOCOLUse bun install not npm install — this repo requires Bun
claude: command not foundRun npm install -g @anthropic-ai/claude-code then restart terminal
Browser doesn't open automaticallyRestart your agent CLI after plugin install; check plannotator is in PATH
build:hook fails with cp errorRun bun run build:review first, then bun run build
Plugin not found in marketplaceMust be inside a Claude Code / Copilot CLI session — not Claude.ai browser chat
Gemini plan mode not triggeringRequires Gemini CLI 0.36.0 or later — run gemini --version to check
05
Undocumented
Hidden Commands & Flags
Power User Zone

These commands exist in the plannotator binary source code but don't appear in the main README. Discovered by inspecting apps/hook/server/index.ts. All verified working in v0.17.10+.

Hidden #01 — Session Management

List, reopen, and clean active Plannotator server sessions HIDDEN

Closed your browser by accident mid-review? You can reopen it — the server is still running.

# List all active Plannotator server sessions plannotator sessions # Reopen session #2 (from the list above) in the browser plannotator sessions --open 2 # Clean up stale session files (zombie servers) plannotator sessions --clean
Life Saver

If your browser crashes or you accidentally close a plan review tab, run plannotator sessions --open 1 to get it back without losing your annotations.

Hidden #02 — The /plannotator-archive Command

Browse every plan decision you've ever made HIDDEN

Not just in the sidebar — there's a dedicated slash command that opens a full-screen read-only archive browser:

# Claude Code / Gemini / OpenCode /plannotator-archive # Direct CLI invocation plannotator archive

Browse all saved decisions from ~/.plannotator/plans/ with approved/denied status badges. Use for audit trails, retrospectives, or seeing "when did we decide to use JWT?"

Hidden #03 — Browser Override Flag

Force a specific browser per-invocation HIDDEN

Don't want Chrome to open? Override with a global flag — works on every subcommand:

# macOS / Linux / Windows plannotator review --browser "Firefox" plannotator annotate README.md --browser "Safari" # Or set the env var globally export PLANNOTATOR_BROWSER="Firefox"
Hidden #04 — PR Review Mode Flags

Control how PR reviews are fetched HIDDEN

When reviewing a PR, Plannotator creates a local checkout by default for full file access. You can disable this for quicker remote-only reviews:

# Default: create local worktree checkout (full file context) plannotator review https://github.com/org/repo/pull/42 # Skip local checkout — remote diff only (faster, less context) plannotator review https://github.com/org/repo/pull/42 --no-local
Why It Matters

Local checkouts use a git worktree under /tmp/plannotator-pr-* so you can navigate the full file tree while annotating. Use --no-local on massive PRs where the checkout is slow.

Hidden #05 — Jina Reader Disable

Turn off URL fetching via Jina on a per-command basis HIDDEN

When annotating a URL, Plannotator uses Jina Reader by default. Disable per-invocation:

# Use native fetch + Turndown instead of Jina plannotator annotate https://example.com/article --no-jina
Hidden #06 — Plan Mode Improve-Context Hook

Inject extra context automatically when the agent enters plan mode SECRET

This is the most hidden feature: drop a script into ~/.plannotator/hooks/ and it will be executed before every plan is shown, letting you inject additional context automatically:

# ~/.plannotator/hooks/improve.sh #!/bin/bash # Returns JSON with additionalContext for the plan review echo '{"additionalContext": "Remember: all new code must include tests."}' # Plannotator automatically invokes this via: plannotator improve-context
Use Case

Inject project-specific rules, security reminders, or coding standards into every plan review without modifying CLAUDE.md.

Hidden #07 — Copilot CLI Subcommands

Dedicated Copilot CLI interception hooks HIDDEN

Copilot CLI uses different subcommands under the hood:

# Intercept exit_plan_mode from Copilot CLI session state plannotator copilot-plan # Annotate the last assistant message from a Copilot session plannotator copilot-last

These are triggered automatically by Copilot CLI's preToolUse hook — you won't usually call them directly.

Hidden #08 — Help & Debug

Show the full hidden command list at any time

plannotator --help # Lists all 8 modes including the hidden ones: # plannotator [--browser ] # plannotator review [PR_URL] # plannotator annotate [--no-jina] # plannotator last # plannotator archive # plannotator sessions [--open N] [--clean] # plannotator improve-context
Hidden #09 — Power User Tips

Things most people don't know

  • 🔑 Plans auto-save before you see them — even if you crash the browser mid-review, ~/.plannotator/history/{project}/{slug}/ has every version
  • 🔄 Deduplication is built in — if Claude resubmits an identical plan, no new file is saved (content hash match)
  • 🏷️ Slug format: {sanitized-heading}-YYYY-MM-DD — same heading on same day = same plan being iterated on
  • 🆔 Auto-resume drafts — annotation drafts are saved to disk via /api/draft and survive server crashes
  • 📷 Drag & drop images — you can attach images to any annotation, stored in ImageAttachment objects with human-readable names
  • 🎯 External API — ESLint, linters, or CI tools can inject annotations via POST /api/external-annotations while a review is live
  • 🔗 VS Code integration — click /api/plan/vscode-diff to open a plan diff directly in VS Code instead of browser
  • 🛡️ SLSA verified — every binary has SHA256 + SLSA provenance (v0.17.2+); verify with --verify-attestation
  • 📝 Obsidian auto-save — plans can be auto-saved to an Obsidian vault with YAML frontmatter; detect vaults via /api/obsidian/vaults
Hidden #10 — Commands I'd Add That Don't Exist Yet

Feature wishlist — not shipped, but you could fork and add these

  • 🔍 /plannotator-search — search archive by heading or date range (plannotator archive --search "auth")
  • 📊 /plannotator-stats — how many plans approved/denied, common annotation patterns, reviewer metrics
  • 🔄 /plannotator-compare — diff two archived plans side-by-side to see how design evolved
  • 📤 /plannotator-export — bulk export archive as a single markdown file for stakeholder reports
  • 🔔 /plannotator-watch — Slack/Teams notification when a plan needs review (team workflow)
  • 💡 /plannotator-replay — replay your annotation session to show a colleague exactly how you reviewed it
  • 📝 /plannotator-template <name> — save frequently-used annotation sets as templates
  • 📢 Submit these via PR at github.com/backnotprop/plannotator
🤖
Agent Tutorial
Claude Code
Full Support

Claude Code has the deepest Plannotator integration — automatic plan interception, visual review, annotations, and team sharing all work out of the box.

Step 1

Install Claude Code and the plannotator binary

npm install -g @anthropic-ai/claude-code irm https://plannotator.ai/install.ps1 | iex
Step 2

Launch Claude Code and register the plugin

claude # Inside the session: /plugin marketplace add backnotprop/plannotator

Restart Claude Code after the plugin installs.

Step 3

Use it — ask Claude to plan something

Plan how you would add OAuth login to this app

Your browser will open automatically with the visual plan UI.

🔷
Agent Tutorial
Codex CLI
⚠ Limited Support

Codex supports code review and annotation commands, but plan mode is not yet available. Commands use ! prefix instead of /.

Step 1

Install Codex CLI and the plannotator binary

npm install -g @openai/codex irm https://plannotator.ai/install.ps1 | iex
Step 2

Launch Codex and use plannotator commands

codex # Inside the session — note the ! prefix: !plannotator review !plannotator review https://github.com/org/repo/pull/42 !plannotator annotate README.md !plannotator last
💎
Agent Tutorial
Gemini CLI
Full Support

Gemini CLI gets full plan mode + code review support. The installer auto-detects Gemini by checking for ~/.gemini. Requires Gemini CLI 0.36.0+.

Step 1

Install Gemini CLI and run the plannotator installer

npm install -g @google/gemini-cli # Installer auto-detects Gemini and configures hooks irm https://plannotator.ai/install.ps1 | iex
Step 2

Use Plannotator inside Gemini CLI

gemini # Enter plan mode — browser opens automatically /plan # Code review commands /plannotator-review /plannotator-review https://github.com/org/repo/pull/42 /plannotator-annotate docs/design.md
🟣
Agent Tutorial
OpenCode
Full Support

OpenCode uses a JSON config file for plugins. After adding the plugin entry and running the installer, restart OpenCode to activate.

Step 1

Add plannotator to your opencode.json config

Find or create opencode.json in your project root:

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

Run the installer to download binary and clear plugin cache

irm https://plannotator.ai/install.ps1 | iex

Restart OpenCode after this step.

Step 3

Use plannotator inside OpenCode

# Plan mode activates automatically # For code review: /plannotator-review /plannotator-review https://github.com/org/repo/pull/42
06
Practical Use
Real-World Examples

These are real prompts and workflows you can copy directly into your agent session.

Example 01 — Refactor Planning

Ask Claude to plan a code refactor, then annotate it

Start a Claude Code session in your project folder, then ask:

Plan how you would refactor the authentication module to use JWT tokens instead of sessions. Show each file you will change and why.

When the browser opens, you can:

  • 🟡 Highlight the JWT section and add a comment: "Use RS256 not HS256 for production"
  • 🔴 Delete any steps touching files you don't want changed
  • ✅ Approve — Claude proceeds with your feedback baked in
Example 02 — New Feature Planning

Plan a new feature before any code is written

Plan the implementation of a dark mode toggle for this React app. Include which components need changes, what CSS variables to add, and how to persist the preference.
Pro Tip

Use Request Changes to send back: "Also add a system preference detection on first load" — Claude will revise the plan and resubmit for another round of review.

Example 03 — PR Review with Annotations

Review an open GitHub Pull Request visually

Inside Claude Code, run:

/plannotator-review https://github.com/your-org/your-repo/pull/47

In the browser, annotate specific lines of the diff. Then click Send Feedback — your annotations are sent back to Claude as structured context so it can explain or fix the code inline.

Example 04 — Annotate a Design Doc

Mark up an architecture markdown file

/plannotator-annotate docs/architecture.md

Great for reviewing AI-generated design docs, sprint plans, or README files before accepting them. Your annotations become feedback Claude acts on immediately.

Example 05 — Team Collaboration Workflow

Share a plan with a colleague for their review

  1. Claude presents a plan → Plannotator opens in your browser
  2. Click the Share button — copies a URL to clipboard
  3. Send the URL to your colleague (Slack, Teams, email)
  4. They open the URL, add their own annotations, click Export Link
  5. You import their annotated link → all feedback merged
  6. Click Send to Agent — combined feedback goes back to Claude
Privacy

Large plans are AES-256-GCM encrypted before upload. The server never sees the content — only you and whoever has the URL can read it.

Example 06 — Remote / SSH Session

Using Plannotator over SSH or in a devcontainer

Set these environment variables before launching your agent:

# Force remote mode (SSH / devcontainer) export PLANNOTATOR_REMOTE=1 export PLANNOTATOR_PORT=9999 # Then forward the port in your SSH config: ssh -L 9999:localhost:9999 user@myserver # Now open http://localhost:9999 in your local browser
07
Configuration
Environment Variables

These variables let you customise Plannotator's behaviour without changing any code. Set them in your shell profile or .env file.

Variable Values Description
PLANNOTATOR_REMOTE 1 / 0 / unset Force remote mode (SSH/devcontainer). Unset = auto-detect via SSH env vars.
PLANNOTATOR_PORT number Fixed port to use. Default: random locally, 19432 for remote sessions.
PLANNOTATOR_BROWSER path/name Custom browser to open plans in. macOS: app name. Linux/Windows: executable path.
PLANNOTATOR_SHARE disabled Set to disabled to turn off URL sharing entirely. Default: enabled.
PLANNOTATOR_SHARE_URL URL Custom base URL for share links if you self-host the portal. Default: https://share.plannotator.ai.
PLANNOTATOR_JINA 0 / 1 Disable/enable Jina Reader for URL annotation. Default: enabled. Also configurable in ~/.plannotator/config.json.
JINA_API_KEY string Optional Jina Reader API key for higher rate limits (500 RPM vs 20 RPM unauthenticated). Free keys include 10M tokens.
PLANNOTATOR_VERIFY_ATTESTATION 1 / true Run gh attestation verify on every install for supply-chain security. Requires gh CLI installed and authenticated.
Persist Settings in config.json

Create ~/.plannotator/config.json to set options permanently without environment variables:

// ~/.plannotator/config.json { "jina": false, "verifyAttestation": true }
08
Tips & Tricks
Best Practices
Best Practice 01 — Always Review Before Approving

Never rubber-stamp a plan

The whole point of Plannotator is to keep you in the loop. Even if the plan looks good, scan each section — AI agents can make subtle scope creep mistakes or touch files you didn't intend. Use highlights to mark sections you want to watch.

Best Practice 02 — Use Request Changes Iteratively

Iterate until the plan is exactly right

Don't approve a plan that's 80% right. Click Request Changes with specific annotations — the agent will revise and resubmit. The Plan Diff feature shows exactly what changed between versions so you can see if your feedback was addressed.

Plan Diff Badge

Look for the +N / -M badge below the plan card. Click it to toggle between normal view and git-style diff view to see exactly what the agent revised.

Best Practice 03 — Be Specific in Annotations

Write actionable comments, not vague ones

  • ❌ Bad: "I don't like this"
  • ✅ Good: "Use dependency injection here instead of importing directly — makes unit testing easier"
  • ❌ Bad: "Change the database part"
  • ✅ Good: "Use a transaction here — both inserts must succeed or fail together"
Best Practice 04 — Pin Versions in Production Workflows

Don't use latest in automated or team setups

If your team uses Plannotator in CI or shared dev environments, pin a specific version to avoid surprise breaking changes:

& ([scriptblock]::Create((irm https://plannotator.ai/install.ps1))) -Version v0.17.10
Best Practice 05 — Use the Archive for Audit Trails

Every decision is saved automatically

All approved and denied plans are saved to ~/.plannotator/plans/ with full version history under ~/.plannotator/history/. Browse them any time via the Archive sidebar tab in any active session. Useful for understanding why a codebase evolved a certain way.

Best Practice 06 — Annotate URLs and Docs Too

Plannotator isn't just for agent-generated plans

You can annotate any URL, HTML file, or markdown file and send feedback back to the agent:

# Annotate a live webpage (fetched via Jina Reader) /plannotator-annotate https://docs.example.com/api-reference # Annotate a local spec file /plannotator-annotate specs/feature-spec.md # Open a folder browser and pick a file /plannotator-annotate ./docs/
09
For Developers
Developer Guidelines

Everything you need to build on top of, extend, or contribute to Plannotator.

Dev — Project Structure

Key folders to know

plannotator/ ├── apps/ │ ├── hook/ # Claude Code plugin (plan review + slash commands) │ ├── opencode-plugin/ # OpenCode plugin │ ├── review/ # Standalone code review editor (Vite dev server) │ ├── vscode-extension/# VS Code extension │ └── paste-service/ # Self-hostable short URL sharing service └── packages/ ├── server/ # Shared Bun server (plan, review, annotate APIs) ├── ui/ # Shared React components, hooks, utilities ├── shared/ # Cross-runtime types, storage, draft persistence ├── editor/ # Plan review App.tsx └── review-editor/ # Code review UI (DiffViewer, FileTree, ReviewSidebar)
Dev — Local Development Setup

Run the dev servers

bun install # Run individual apps bun run dev:hook # Plan review hook server bun run dev:review # Code review editor bun run dev:portal # Share portal bun run dev:marketing # plannotator.ai website bun run dev:vscode # VS Code extension (watch mode) # Test the plugin locally without installing claude --plugin-dir ./apps/hook
Dev — Build Order (Critical)

Build order matters — always follow this sequence

The hook build copies pre-built HTML from the review app. If you skip the review build, you'll get stale files.

# If you changed UI code in packages/ui or review-editor: bun run --cwd apps/review build && bun run build:hook # If you only changed plan UI (not review UI): bun run build:hook # For OpenCode plugin: bun run build:hook && bun run build:opencode # Full compile to binary (for local testing): bun run --cwd apps/review build && bun run build:hook && bun build apps/hook/server/index.ts --compile --outfile ~/.local/bin/plannotator
⚠ Common Mistake

Running only bun run build after changing review-editor code will silently copy stale HTML. Always run build:review first.

Dev — Key API Endpoints

Server API surface (all servers use random port locally, 19432 in remote)

GET /api/plan
Returns plan markdown, origin, version info, previousPlan for diff
POST /api/approve
Approve plan — sends allow decision back to agent hook
POST /api/deny
Deny plan with feedback — sends deny + message back to agent
GET /api/diff
Review server: returns rawPatch, gitRef, diffType, gitContext
POST /api/feedback
Submit review/annotate feedback with annotations array
GET/POST /api/draft
Auto-save annotation drafts — survives server crashes
POST /api/external-annotations
Inject annotations from external tools (e.g. ESLint, linters)
GET /api/external-annotations/stream
SSE stream for real-time external annotation updates
Dev — External Annotations API

Inject annotations from external tools programmatically

Any tool (linters, CI, custom scripts) can push annotations into the active Plannotator session via the REST API:

# Single annotation curl -X POST http://localhost:19432/api/external-annotations \ -H "Content-Type: application/json" \ -d '{"source": "eslint", "type": "COMMENT", "originalText": "var x = 1", "text": "Use const instead of var"}' # Batch annotations curl -X POST http://localhost:19432/api/external-annotations \ -H "Content-Type: application/json" \ -d '{"annotations": [{"source": "eslint", "type": "COMMENT", ...}, ...]}'
Dev — Contributing

How to submit a contribution

  1. Fork the repo at github.com/backnotprop/plannotator
  2. Run bun install and bun run dev:hook to verify the dev environment works
  3. Make your changes — if touching server endpoints, update both the Bun server (packages/server/) and the Pi server (apps/pi-extension/server/)
  4. Put runtime-agnostic logic in packages/shared/ so all runtimes benefit
  5. Test locally with claude --plugin-dir ./apps/hook
  6. Submit a Pull Request — dual licensed MIT / Apache 2.0
⚠ Two Server Runtimes

There are two server implementations with the same API surface — Bun (used by Claude Code + OpenCode) and Node.js (used by Pi). If you add or change any server endpoint, you must update both.