backnotprop__plannotator/README.md

Everything you need to annotate and stay in the loop with your agents
Markdown Review • Code Review • HTML Artifacts
_{Annotate plans, specs, markdown, and HTML before implementation. Review diffs and PRs. Send feedback to your agent.}

                       

Watch the og demo · Installation guide · Official site · Visual HTML Skills

Plannotator

Plannotator is a local, browser-based review surface for AI coding agents: Claude Code, Codex, Copilot CLI, Gemini CLI, OpenCode, Kiro, Droid, Amp, and Pi.

It plugs directly into your agent through its hooks and commands. When the agent proposes a plan, html, or finishes writing code, the work opens in your browser and you mark it up, comment, and send feedback directly to the agent for it to act on it.

Review documents, plans, and agent messages Annotate plans, specs, messages, html, then send the feedback to your agent. Demo: Plan review with Pi
Code Review Review local changes or remote PRs. Comment on diffs, suggest code. Your comments go back to the agent. Works with git, jj, p4, GitHub, and GitLab.

_{AI built in: ask AI about anything you're reviewing,
or launch AI reviews that post comments to the diff.}

Annotate HTML Artifacts

---

Commands

_{On Codex, swap the slash commands for !plannotator … (e.g. !plannotator review) or the $plannotator-* skills.}

Annotate

/plannotator-annotate README.md                  # Local markdown file
/plannotator-annotate src/                       # Browse and annotate files in a folder
/plannotator-annotate https://docs.rs/…          # Fetch and annotate any URL
/plannotator-annotate report.html --render-html  # Render HTML as-is instead of converting
/plannotator-last                                # Annotate the agent's last message

Code review

/plannotator-review                    # Review uncommitted changes
/plannotator-review <github-pr-url>    # Review a GitHub pull request
/plannotator-review <gitlab-mr-url>    # Review a GitLab merge request

Plan mode

No command needed. Plan mode is wired in through each harness's hooks. Any time your agent creates a plan, the markdown review surface opens for you.

CLI

plannotator sessions                   # List active Plannotator sessions
plannotator sessions --open 1          # Reopen a session in the browser
plannotator archive                    # Browse saved plan decisions read-only

---

Sharing & Multiplayer

_{Beta: room.plannotator.ai}

Share a plan with a teammate and they can annotate it themselves. Import their feedback and send it straight back to your agent.

Small plans are encoded entirely in the URL hash. No server involved. The data lives in the link itself.

Large plans go through a short-link service, encrypted in your browser with AES-256-GCM. The server stores only ciphertext, and the key never leaves the URL fragment. Pastes auto-delete after 7 days.

Same model as PrivateBin. The paste service is self-hostable.

Sharing can be disabled entirely with PLANNOTATOR_SHARE=disabled.

Coming next: live collaboration. Teammates and their agents working through the same plan or review together, in real time. It arrives in Workspaces once the room beta wraps. Sign up here.

---

Install

One installer covers almost every agent. It installs the plannotator binary, auto-detects your installed agents, and configures hooks, skills, and slash commands for each:

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

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

Want just the binary and nothing else? Pass --minimal (or export PLANNOTATOR_MINIMAL=1) to install only the plannotator binary to ~/.local/bin, skipping every skill, hook, slash command, and per-agent config:

curl -fsSL https://plannotator.ai/install.sh | bash -s -- --minimal

Then finish the step for your agent:

Agent	After the installer	Details
Amp	Copy plannotator.ts into ~/.config/amp/plugins/, then plugins: reload. Workflows live in the command palette.	README
Claude Code	/plugin marketplace add backnotprop/plannotator, then /plugin install plannotator@plannotator. Restart Claude Code.	README
Codex	Nothing. Plan review is enabled automatically via Codex's experimental Stop hook (macOS/Linux/WSL; Codex hooks are disabled on Windows). $plannotator-review, $plannotator-annotate, and $plannotator-last skills included.	README
Copilot CLI	/plugin marketplace add backnotprop/plannotator, then /plugin install plannotator-copilot@plannotator. Restart. Plan review activates in plan mode (Shift+Tab).	README
Droid	droid plugin marketplace add https://github.com/backnotprop/plannotator, then droid plugin install plannotator@plannotator. Commands only, no plan interception yet.	README
Gemini CLI	Nothing. The hook, policy, and slash commands are configured automatically. Requires Gemini CLI 0.36.0+.	README
Kiro CLI	Nothing. Skills and an example agent are installed automatically. Try kiro-cli chat --agent plannotator.	README
OpenCode	Add "plugin": ["@plannotator/opencode@latest"] to opencode.json. Restart OpenCode.	README
Pi	Skip the installer. Just pi install npm:@plannotator/pi-extension. Start Pi with --plan, or toggle with /plannotator.	README

Full walkthroughs live in the installation docs.

Claude Code: manual hook setup (without the plugin system)

Add to ~/.claude/settings.json:

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

Pin a specific version

curl -fsSL https://plannotator.ai/install.sh | bash -s -- --version vX.Y.Z

& ([scriptblock]::Create((irm https://plannotator.ai/install.ps1))) -Version vX.Y.Z

Try it

The fastest way to see what Plannotator does is to invoke it yourself, right now, from your agent:

/plannotator-last                   # annotate the agent's last reply
/plannotator-review                 # review your current diff, PR-style
/plannotator-annotate report.html   # annotate any file, folder, or URL

(Slash commands in most agents; $plannotator-* skills in Codex, command palette in Amp.)

Plan review needs no command at all. The next time your agent proposes a plan, it opens in your browser automatically.

---

How it works

Plan review

Agent calls ExitPlanMode
  -> PermissionRequest hook fires
  -> Local server reads plan from hook input
  -> Browser opens with review UI
  -> You annotate and approve/deny
  -> Approve: agent proceeds
  -> Deny: structured feedback sent to agent
  -> Agent revises, plan diff shows what changed

Code review

You run /plannotator-review
  -> git diff captures changes (or PR fetched by URL)
  -> Browser opens with diff viewer
  -> Annotate lines, stage/unstage files
  -> Send feedback: returned to agent session
  -> Approve: "LGTM" sent

---

Integrations

VS Code: Open plans in editor tabs, view diffs inline, add annotations from the editor gutter. Install from the VS Code Marketplace.

Obsidian: Auto-save approved plans to a vault with YAML frontmatter, tags from the plan title, and backlinks for graph connectivity. Configure in Plannotator's Settings panel.

Bear: Save plans as Bear notes with nested tags and project metadata.

GitHub / GitLab: Pass any PR or MR URL to /plannotator-review and review it with the full diff viewer, annotations, and file tree.

---

Remote / SSH / devcontainer

Plannotator auto-detects SSH sessions and switches to a fixed port. For explicit control:

export PLANNOTATOR_REMOTE=1
export PLANNOTATOR_PORT=9999  # forward this port

VS Code devcontainers forward the port automatically (check the Ports tab). For raw SSH, add to ~/.ssh/config:

Host your-server
    LocalForward 9999 localhost:9999

---

Security

Every released binary ships with a SHA256 sidecar. SLSA provenance attestations are available from v0.17.2.

To verify on install:

curl -fsSL https://plannotator.ai/install.sh | bash -s -- --verify-attestation

Requires gh installed and authenticated. Can also be set persistently in ~/.plannotator/config.json:

{ "verifyAttestation": true }

See the verification docs for details.

---

Configuration

Settings are saved in cookies (not localStorage) because each hook invocation runs on a random port. You can also set options through environment variables or ~/.plannotator/config.json.

Variable	Description
PLANNOTATOR_REMOTE	1/true for remote mode, 0/false for local, unset for SSH auto-detection
PLANNOTATOR_PORT	Fixed port (default: random locally, 19432 remote)
PLANNOTATOR_BROWSER	Custom browser to open plans in
PLANNOTATOR_SHARE	disabled to turn off URL sharing
PLANNOTATOR_SHARE_URL	Custom base URL for share links (self-hosted portal)
PLANNOTATOR_PASTE_URL	Base URL of the paste service API
PLANNOTATOR_ORIGIN	Override agent detection: claude-code, amp, droid, opencode, codex, copilot-cli, gemini-cli, kiro-cli, pi
PLANNOTATOR_JINA	0/false to disable Jina Reader for URL annotation
JINA_API_KEY	Jina Reader API key for higher rate limits

---

Development

bun install

bun run dev:hook       # Plan review server
bun run dev:review     # Code review editor
bun run dev:marketing  # Marketing site (plannotator.ai)
bun run dev:vscode     # VS Code extension (watch mode)

Build

bun run build          # Main targets (hook + opencode)
bun run build:hook     # Single-file HTML for the hook server
bun run build:review   # Code review editor
bun run build:opencode # OpenCode plugin
bun run build:vscode   # VS Code extension

Build order matters. The hook build copies pre-built HTML from apps/review/dist/. If you change UI code in packages/ui/, packages/editor/, or packages/review-editor/, rebuild the review app first:

bun run --cwd apps/review build && bun run build:hook

Test the plugin locally:

claude --plugin-dir ./apps/hook

Full binary build:

bun run --cwd apps/review build && bun run build:hook && \
  bun build apps/hook/server/index.ts --compile --outfile ~/.local/bin/plannotator

---

License

Copyright 2025-2026 backnotprop

Dual-licensed under Apache 2.0 or MIT at your option.

Contributions are dual-licensed under the same terms unless you explicitly state otherwise.