Developer tools#Coding agent#Code review

Plannotator: a review desk for agent plans and diffs

Plannotator opens agent plans and diffs in a local browser UI, so you annotate them in place and your notes return to the session as structured feedback.

Project facts

GitHub Ecosystem
Repositorygithub.com/backnotprop/plannotator
License
Apache-2.0
Language
TypeScript
Stars
12,742
Data checked
2026-11-17

Snapshot figures reflect the check date and may change over time.

GitHub repository card for backnotprop/plannotator with the repo name, one-line description, owner avatar, and contributor, issue, star and fork counts

Reading a plan an agent wrote can be harder than reading its code. A plan arrives as one block of Markdown, and the only way to remove item three or reword item five is to describe the change in the chat box and hope the agent guesses which sentence you meant. Plannotator moves that exchange into the browser: when an agent is about to leave plan mode, or finishes a round of edits, it starts a page on localhost where you highlight text, comment on diff lines, and press send, and your notes return to the same session as structured feedback. The repository, backnotprop/plannotator, was created on 2025-12-28 and had 12,742 stars on 2026-11-17.

GitHub's repository card for backnotprop/plannotator, showing the repo name, description and 13k stars

Key points

  • Deployment shape: one plannotator binary plus a local HTTP server, with the interface in your browser and a hook, plugin or command per agent. There is no cloud account; review data lives under ~/.plannotator by default.
  • Coverage: the README’s install table lists 11 clients — Amp, Claude Code, Codex, Copilot CLI, DeepSeek Harness, Droid, Gemini CLI, Kiro CLI, OpenCode, Pi and T3 Code. Other agents can reach the Inbox over plannotator inbox mcp.
  • Cadence: 229 releases so far, the newest v0.28.66 on 2026-11-16, and the repo took a push on 2026-11-17. It is not archived.
ItemValue (checked 2026-11-17)
Stars / forks12,742 / 1,256
LicenseApache-2.0 (the README offers Apache 2.0 or MIT)
LanguageTypeScript
Created2025-12-28
Latest releasev0.28.66, 2026-11-16

Core features

Every Plannotator feature serves one purpose: turning your opinion about a document into something the agent can act on in its next turn.

  • Plan interception: on Claude Code the PermissionRequest hook catches ExitPlanMode, a local server reads the plan out of the hook input, and the browser opens the review UI. Approve and the agent continues; deny and your annotations go back as structured feedback, so the revised plan arrives with a diff against the old one. No command needed.
  • Diff review: /plannotator-review captures git diff HEAD in a diff viewer, and also takes a GitHub PR or GitLab MR URL, or plannotator review --gitbutler for an active GitButler workspace. Git is not the only backend: GitButler, Jujutsu (jj) and Perforce (p4) are all named in the README.
  • Annotations as input: in the review surface you can mark a passage for deletion, leave an inline comment, or write a replacement; on a diff you comment on lines, attach suggested code, and stage or unstage files while you are there. Approving sends LGTM; rejecting sends structured notes back to the agent (the README does not specify the format).
  • Guided review: press Guide (or Cmd/Ctrl+Shift+G) and an agent sorts the diff into chapters, the heart of the change first, each with a short overview beside the real diff. On a large change that beats scrolling from line one.
  • HTML and local sites: /plannotator-annotate report.html --render-html annotates rendered HTML, and plannotator annotate http://localhost:5173 opens a running frontend through a local proxy with hot reload intact. The six self-contained HTML skills in effective-html, which we covered in October, produce exactly the artifacts this view is built to mark up.

Plannotator's annotation view: a document outline and sections on the left, a highlighted paragraph in the middle, two annotations on the right, and the Claude Code terminal that opened it

Where it runs

Plannotator is not another hosted web app, and its deployment model matters more than a feature list.

  • A local process plus a browser: each hook invocation starts a server on a random port and serves a single-file HTML app, then goes away. Because the port changes every time, UI settings are stored in cookies rather than localStorage.
  • Remote and containers: an SSH session switches to a fixed port of 19432; inside a devcontainer or Docker you set PLANNOTATOR_REMOTE=1 and PLANNOTATOR_PORT, then forward the port.
  • Where the data goes: plans, annotations, drafts and config sit in ~/.plannotator, relocatable with PLANNOTATOR_DATA_DIR. The feedback archive is on by default and keeps review text and quoted excerpts but not the diff; the privacy page says plainly that nothing prunes the directory, so records stay until you delete them or set PLANNOTATOR_FEEDBACK_HISTORY=0.
  • Network edges: once a day, for each tool you use, it sends an anonymous ping to ping.plannotator.ai carrying the tool name, version and age in weeks but no identifier; NO_ANON_PING=1 turns it off. The homepage says “no usage telemetry” while the privacy page describes the daily ping — they disagree, and the privacy page is the accurate one.
  • Sharing is optional: small plans are compressed into the URL fragment (compressed, not encrypted — anyone with the full link can read it); larger ones are encrypted with AES-256-GCM before upload, and the hosted paste service deletes the ciphertext after seven days while the key stays in the fragment. PLANNOTATOR_SHARE=disabled turns the whole thing off.

Typical use cases

  • Make the agent show its plan first: hand a task to Claude Code, annotate the plan, then let it run. Cheaper than reviewing 20 changed files and rolling back. The author’s January 3, 2026 blog post says the project started from exactly that gap: agents write plans, but the interface for reading and editing one lagged behind.
  • Several sessions in a day: with agents running in parallel, each one eventually waits on a decision. plannotator inbox collects those requests into one local window so a session is not held open while you are away; Claude Code, Pi and OpenCode connect through plugins, and other agents through MCP.
  • Reviewing someone else’s large PR: /plannotator-review <PR URL> opens the full diff view; guided review gives you chapters first, and your comments can go to your own agent session or back to the author.
  • A designer or PM reading a prototype: send a plan or an HTML artifact as a link, let them annotate in the browser, then import their feedback for the agent. This is the collaborative edge of the tool; the team layer, Workspaces, is still a waitlist.

Plannotator's code review view: a file tree with change counts on the left, a side-by-side diff in the middle, an annotation box on one line, and an Approve button top right

Quick start

The installer drops the binary, detects the agents you already have, and configures hooks, skills and slash commands for each:

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

If you want only the binary, add --minimal: it puts plannotator in ~/.local/bin and touches nothing else. Then try three commands from inside your agent to see what it does:

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

Plan review needs no command at all; the browser opens the next time your agent proposes a plan. Finishing steps differ by client, and the README table is the accurate one. The rows that surprise people:

ClientWhat is left to do after the installer
CodexNothing: it runs off Codex’s experimental Stop hook; commands become $plannotator-* skills
Claude CodeAfter the installer: /plugin marketplace add backnotprop/plannotator, then /plugin install plannotator@plannotator, restart
PiSkip the installer: pi install npm:@plannotator/pi-extension, start with --plan
DroidCommands only, no plan interception yet
Gemini CLIConfigured automatically, requires Gemini CLI 0.36.0 or newer

Summary

Plannotator is for people who use a coding agent every day and actually read its plans. It swaps “let me describe which sentence I want changed” for “let me mark it”, and the shape of the feedback is what cuts the rework. It also suits anyone reviewing a pull request without pushing the branch anywhere first. It does not suit a workflow where you never read the plan and just check the result: an extra window is then just an extra step.

The license is Apache-2.0, with MIT offered as an alternative in the README, so either applies. It is written in TypeScript and had 12,742 stars on 2026-11-17. Compared with OpenCodeReview, which we covered on November 15, it takes the opposite side of the same problem: that tool has AI write the review comments for a human to skim, while Plannotator has the human write them for the AI to execute. Which one you want depends on whose eyes you trust.

Three things to know before you install it. Remote mode listens on 0.0.0.0 with no login, so anyone who can reach the port can use it, and the README itself says to keep that port off untrusted networks. Client support is uneven: Droid still has no plan interception, and everything else rides on each agent’s hooks, which an agent upgrade can break. And while the release side is more careful than most — a SHA256 sidecar on every binary, SLSA provenance since v0.17.2, a CycloneDX SBOM checked with Grype before anything is published — the verification is opt-in: a normal install does not run --verify-attestation.