Plannotator: A Local Review Surface for AI Coding Agent Plans and Diffs

The Problem Plannotator Solves

AI coding agents write plans and produce diffs, but the review step is typically ad hoc. A developer reads the plan in the terminal, decides what to change, and either types a response in chat or edits the files manually. There is no structured surface for marking up the plan, attaching comments to specific lines, and returning that feedback as the agent's next input.

Plannotator addresses this by hooking into the agent's lifecycle. Through each harness's hooks and commands, it intercepts plans, markdown documents, and code diffs and opens them in a browser-based annotation interface. The developer marks up the content, and one click sends the annotated feedback back to the agent as its next message.

The project supports Claude Code, Codex, Copilot CLI, Gemini CLI, OpenCode, Kiro, Droid, Amp, and Pi. Each harness integrates through its own hook mechanism. The README notes that on Codex the slash commands are replaced with `!plannotator` prefixes instead.

Three Review Surfaces: Documents, Diffs, and HTML

Plannotator provides three distinct review modes.

The document and plan review mode opens markdown files, agent messages, fetched URLs, and HTML artifacts for annotation. The `/plannotator-annotate` command accepts a local file path, a directory to browse, or a URL:

/plannotator-annotate README.md
/plannotator-annotate src/
/plannotator-annotate https://docs.rs/…
/plannotator-annotate report.html --render-html
/plannotator-last

The `--render-html` flag renders an HTML file as a page rather than converting it to markdown. `/plannotator-last` opens the agent's most recent message for annotation.

The code review mode works against uncommitted changes, remote pull requests, or other diff sources:

/plannotator-review
/plannotator-review <github-pr-url>
/plannotator-review <gitlab-mr-url>
plannotator review --gitbutler
plannotator review --patch-file reading.diff

Supported version control backends include Git, GitButler, Jujutsu (`jj`), and Perforce (`p4`). GitHub and GitLab pull requests are fetched via the authenticated CLI and Git remote.

The HTML artifact review mode opens agent-generated HTML files as rendered pages. Comments placed on the page are then routed back to the agent.

Plan mode requires no command. The README states it is wired in through each harness's hooks: any time the agent creates a plan, the markdown review surface opens automatically.

Installing and Using the CLI

Plannotator is distributed as a Node.js package with a `plannotator` CLI binary. The package.json defines `bin/plannotator.js` as the entry point. The version at the time this article was written is 0.27.21.

For terminal-based review without the full application, the README describes Herdr Annotate, a companion plugin:

herdr plugin install plannotator/herdr-annotate

This brings Plannotator-style annotation into the Herdr terminal environment and works with Claude Code, Codex, Pi, Copilot CLI, and Droid replies. Annotations are saved to the Plannotator data directory, so terminal reviews and app reviews share the same history.

For users who want document review without Herdr:

brew install plannotator/tap/plannotator-tui

This installs Plannotator TUI, a standalone terminal tool for document review.

The CLI also exposes session management:

plannotator sessions
plannotator sessions --open 1
plannotator archive

`plannotator sessions` lists active sessions. `plannotator archive` opens saved plan decisions in a read-only view.

Privacy Model and Network Behavior

Plannotator's default mode keeps everything local. The README states that plans, diffs, annotations, drafts, history, and configuration stay local by default. No usage telemetry is collected.

When pages load, each surface checks GitHub for the latest Plannotator release. The README notes this sends no plan or review content and provides no usage analytics, though GitHub receives an ordinary HTTPS request. There is no opt-out for this check.

Local Git code review queries the configured `origin` with `git ls-remote` to detect the default branch and check for a stale baseline. The query runs when the review opens and when the diff is refreshed, never on a timer. To disable it entirely, the README documents three options: the `--no-git-remote-check` flag, the `PLANNOTATOR_GIT_REMOTE_CHECK=0` environment variable, or setting `{ "gitRemoteCheck": false }` in `~/.plannotator/config.json`.

Content leaves the local machine only when a network feature is explicitly used: URL annotation fetches the target site, GitHub and GitLab review uses the authenticated CLI, Ask AI sends context to the configured provider, and sharing uploads to a paste service. The MCP server at `/mcp` is accessible to external tools like Claude Code and Cursor; the README notes it can operate on any mailbox by passing parameters, and the Cloudflare Access policy is the single trust boundary in deployed environments.

Limitations and What It Does Not Cover

Plannotator is a review surface, not a test runner or linter. It does not check code correctness, run unit tests, or enforce style rules. The feedback loop is human: the developer reads the plan, annotates it, and sends the annotation back. The tool cannot automate the review judgment itself.

The release check on page load is hardwired with no opt-out. For environments where outbound requests to GitHub are blocked by policy, the check will fail silently or cause errors each time a review surface loads.

The MCP server at `/mcp` provides access to all mailboxes without per-mailbox authorization. The README is explicit: the Cloudflare Access policy is the only trust boundary. Any principal that passes the shared Access policy can operate on every mailbox. Teams with strict per-user data isolation requirements should evaluate this constraint before deploying.

A comparison point is GitHub's built-in PR review interface, which also supports inline comments on diffs. GitHub's interface requires code to be pushed to a remote repository before it can be reviewed, and feedback is stored as PR comments rather than being routed directly back to an agent. Plannotator works on local, uncommitted changes and connects the review output to the agent's input, which is the structural difference.

Editorial conclusion

Plannotator is the right tool for a developer who regularly reviews agent plans or code diffs and wants to annotate them and send feedback without copy-pasting between the terminal and a text editor. The feedback loop between the review surface and the agent is the main differentiator. Developers who accept agent output without manual review, or who do all review in GitHub's own PR interface, will find less value here. Version 0.27.21 was published on 2026-09-26, and the repository's last push was on 2026-09-25.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes