Plannotator: A local review surface that sends your markup straight back to the agent

The problem: agents propose, humans rubber-stamp

AI coding agents produce plans, markdown specs, HTML artifacts, and large diffs. Reviewing those inside a terminal or a chat pane is cramped. Comments get lost, context gets truncated, and sending structured feedback back into the agent's next message is manual. Plannotator targets exactly that gap. It is for engineers who let an agent write code but still want a human checkpoint before the agent acts. The README positions it as a review surface for Claude Code, Codex, Copilot CLI, Gemini CLI, OpenCode, Kiro, Droid, Amp, and Pi. The tool does not replace the agent. It sits between the agent's output and the next action, letting you annotate and then push comments back as the agent's next input.

How the feedback loop works

Plannotator hooks into each agent harness through hooks and commands. When the agent proposes a plan, generates HTML, or finishes writing code, the work opens in your browser. You mark it up, comment, and send feedback directly to the agent. The README says it plugs directly into your agent. For code review, the tool reads local changes or remote PRs and MRs. It supports Git, GitButler, Jujutsu (jj), Perforce (p4), GitHub, and GitLab. The data flow is local-first: plans, diffs, annotations, drafts, history, and configuration stay local by default. There is also an AI layer built in. You can ask AI about anything you are reviewing, or launch AI reviews that post comments to the diff. That AI integration sends your selected question and relevant context to your configured provider, so it is not a local model by default.

Commands and surfaces: from files to PRs to last message

The command set is concrete and varied. For annotation, you run /plannotator-annotate README.md for a local file, /plannotator-annotate src/ to browse a folder, or /plannotator-annotate https://docs.rs/... to fetch a URL. The --render-html flag renders HTML as-is instead of converting it. There is also /plannotator-last to annotate the agent's last message. For code review, /plannotator-review covers uncommitted changes, a GitHub PR URL, or a GitLab MR URL. GitButler users can run plannotator review --gitbutler to review the whole workspace, one stack, or one branch layer. Plan mode needs no command; it is wired through each harness's hooks, so any time the agent creates a plan, the markdown review surface opens. The CLI also has plannotator sessions to list or reopen sessions, and plannotator archive to browse saved plan decisions read-only. On Codex, you swap slash commands for !plannotator or $plannotator-* skills.

Getting it running: installation and setup

The README points to an installation guide at docs.plannotator.ai/open-source/start/installation. The Herdr plugin path is: herdr plugin install plannotator/herdr-annotate. That plugin brings Plannotator-style review to the terminal inside Herdr, and it works with Claude Code, Codex, Pi, Copilot CLI, and Droid replies. If you want the standalone TUI without Herdr, you can brew install plannotator/tap/plannotator-tui. For the main browser app, follow the installation guide. The README also links to a product requirements document template as a realistic file to try with /plannotator-annotate.

Privacy boundaries: local by default, but not silent

The privacy section is the most detailed part of the README, and it is worth reading carefully. Plannotator does not collect usage telemetry or analytics. Plans, diffs, annotations, drafts, history, and configuration stay local by default. However, each plan review, annotate, archive, share-portal, and code-review app surface checks GitHub for the latest Plannotator release when it loads. That sends no plan or review content, but GitHub receives an ordinary request. There is currently no opt-out setting. Local Git code review can also query the configured origin with git ls-remote to detect the default branch and a stale baseline; it does not send the local diff. Content leaves the local workflow only when a network feature needs it: URL annotation fetches the requested site through Jina Reader by default, GitHub and GitLab review uses your authenticated CLI, Ask AI sends context to your provider, and sharing uploads ciphertext to a paste service. The open source app's local-storage model does not apply to Workspaces, a separate hosted product.

Limitations: the release check, Jina Reader, and the sharing deprecation

The most obvious limitation is the un-opt-outable GitHub release check. If you are on a strict network policy or an air-gapped machine, every load of a review surface makes an outbound request. That is not a data leak of your plans, but it is a network call you cannot disable. The second limitation is URL annotation. By default, fetching a URL goes through Jina Reader, a third-party service. You can disable Jina or it falls back to direct fetching when unavailable, but the default path sends the URL to an external reader. The third limitation is the link-sharing feature. The README states that open source asynchronous link sharing is moving to deprecated support, and Workspaces is the primary direction for team sharing. No removal date has been announced, but if you rely on the legacy link-sharing demo at room.plannotator.ai, you should plan for it to disappear. For teams that need persistent shared review rooms, the hosted Workspaces product is the intended path, which means your data then lives outside your local machine.

Alternatives: terminal review and agent-native loops

The closest alternative is Herdr Annotate, which the Plannotator project itself maintains. It brings the same annotation model into the terminal, works inside Herdr, and saves annotations to the same Plannotator data directory, so terminal reviews and app reviews compound. That is a complementary tool rather than a competitor. A more fundamental alternative is to skip a dedicated review surface and rely on the agent's built-in plan approval or a simple copy-paste of comments back into the chat. That approach has zero extra network calls and no install, but it loses the visual diff context and the structured annotation. Plannotator's difference is the bidirectional loop: your annotations become the agent's next message. Herdr Annotate does the same in a terminal, while the browser app gives you a richer surface for HTML and large diffs.

Maintenance, license, and what to verify before adopting

GitHub reports the repository as Apache-2.0, while package.json declares MIT OR Apache-2.0 and both LICENSE-APACHE and LICENSE-MIT are present. Apache-2.0 permits commercial use, modification, and distribution with attribution. The project is actively maintained, with releases v0.28.45, v0.28.46, and v0.28.47 published within a single day, on 2026-11-02. That cadence suggests ongoing fixes, but it also means you should expect frequent updates. Test an upgrade on a non-critical session before relying on it. Before adopting, verify that your agent harness has the hooks described. The README lists many agents, but hook wiring is per-harness and may require manual setup. Also confirm that your version control system is supported: Git, GitButler, Jujutsu, Perforce, GitHub, and GitLab are named, but if you use something else, the code review path may not work. Finally, test the feedback path on a single plan to see if the round-trip matches your review speed. The tool is only useful if the agent actually consumes the comments you send.

Editorial conclusion

Adopt Plannotator if you work daily with Claude Code, Codex, Copilot CLI, Gemini CLI, OpenCode, Kiro, Droid, Amp, or Pi and want a visual review loop that does not leave your machine. Skip it if you need fully offline operation with zero outbound requests, because each app surface checks GitHub for releases with no opt-out, and URL annotation uses Jina Reader by default. Before adopting, verify that your agent's hook wiring matches the documented setup, confirm your Git or Perforce workflow is supported, and test the feedback path on a single plan to see if the round-trip matches your review speed.

Frequently asked questions

Official sources

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