Plannotator

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.}

Copilot CLI OpenCode

Watch the og demo · Installation guide · Official site

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

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

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

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

Name		Name	Last commit message	Last commit date
Latest commit History 704 Commits
.agents/skills		.agents/skills
.claude-plugin		.claude-plugin
.factory-plugin		.factory-plugin
.github		.github
apps		apps
bin		bin
packages		packages
scripts		scripts
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE-APACHE		LICENSE-APACHE
LICENSE-MIT		LICENSE-MIT
README.md		README.md
bun.lock		bun.lock
bunfig.toml		bunfig.toml
openpackage.yml		openpackage.yml
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Plannotator

Review documents, plans, and agent messages

Code Review

Annotate HTML Artifacts

Commands

Annotate

Code review

Plan mode

CLI

Sharing & Multiplayer

Install

Try it

How it works

Plan review

Code review

Integrations

Remote / SSH / devcontainer

Security

Configuration

Development

Build

License

About

Licenses found

Uh oh!

Releases 114

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Plannotator

Review documents, plans, and agent messages

Code Review

Annotate HTML Artifacts

Commands

Annotate

Code review

Plan mode

CLI

Sharing & Multiplayer

Install

Try it

How it works

Plan review

Code review

Integrations

Remote / SSH / devcontainer

Security

Configuration

Development

Build

License

About

Topics

Resources

License

Licenses found

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 114

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages