Plannotator: Annotate Agent Plans and Review Code Before Claude Code or Codex Runs

Plannotator is a free, local-first workspace that lets you mark up a coding agent's plan and review its code before you accept it. The repository, backnotprop/plannotator, trended on GitHub this week with about 100 new stars in a day and roughly 10,256 stars in total. It works with Claude Code, Codex, OpenCode, Gemini CLI, Copilot CLI and several other agents.

The idea is simple. Agents now write long plans and large diffs. Reading them in a terminal scrollback is a poor way to catch mistakes. Plannotator opens a browser tab at the moment that matters, so you can comment on exactly the line you disagree with.

We read the README and the product site for this post. We did not run the installer in this unattended session, so every behavior below comes from those sources, and we flag the places where you should check for yourself.

TL;DR: what Plannotator does and what to check

What problem does Plannotator solve?

Coding agents propose a plan, then act. The weak point is the handoff. When the plan is a wall of text in a terminal, most people skim it and type "looks good." That is the failure mode Addy Osmani described as cognitive surrender: the human stops checking because checking is tedious.

The review burden is also real. Our guide to AI brain fry and the git queue covers how fast a developer's attention runs out when several agents produce changes at once. A tool that makes each review quicker and more precise addresses the same bottleneck from a different side.

Plannotator's answer is to give the review its own surface. The site's tagline is "Plan and code review for your agents," and its closing line is "Your next plan deserves more than a rubber stamp."

How does Plannotator work with Claude Code and Codex?

A magnifying lens inspecting one tile, showing how Plannotator lets you review a single plan step before the agent acts

The product has three main modes, each tied to a command.

Plan review runs automatically at the agent's plan step. The site says you can add inline comments, mark deletions, write replacements, and view version history with diffs between plan revisions. When you finish, the feedback goes back to the agent as structured input rather than a pasted block of prose.

Code review looks like a pull request tool. The README and site describe side-by-side or unified diffs, a file tree, line-level annotations with code suggestions, and staging or unstaging of files. Drafts auto-save, so a crash or restart does not lose your comments.

On Codex you call it with !plannotator or with $plannotator-* skills. That follows the same pattern as agent skills: a small instruction pack that the agent reads, here pointing at a review tool.

The Inbox and terminal views

The README also lists a Plannotator Inbox, one local window for agent questions, files and guided reviews, plus terminal-based options (Herdr Annotate and a Plannotator TUI). The Inbox is described as working with personal assistants as well, including Hermes and OpenClaw. We could not verify those integrations from the page alone, so treat that part as the maintainer's claim.

How do I install Plannotator?

The README gives these paths. Run only what you have read.

If you use Claude Code, start with the plugin route and read our plan mode guide first, because Plannotator hooks into that plan step. Our Claude Code commands reference covers the slash-command mechanics. For OpenCode users, the OpenCode guide explains how its plugin list works.

Is Plannotator safe? Privacy, sharing and supply chain

This is the part to read before you install anything that sits between you and an agent with shell access.

What the README promises. "Plannotator does not collect usage telemetry or analytics." Plans, diffs and annotations stay local by default.

What it still does. Each review surface checks GitHub for the latest release on load, and the README says there is no opt-out for that check. Local Git review may run git ls-remote against your origin. You can disable that with PLANNOTATOR_GIT_REMOTE_CHECK=0.

Share links. Small markdown shares are compressed into the URL fragment, which the README states is "not encrypted." Anyone with the link can read it, and links travel through chat apps and browser history. Larger shares are encrypted with AES-256-GCM before upload, and hosted pastes expire after 7 days. Set PLANNOTATOR_SHARE=disabled if you never want sharing. The README also says link sharing is moving toward deprecated support, with Workspaces as the hosted team product, whose data handling differs from the local app.

Supply chain. Releases ship with SHA256 sidecars and SLSA provenance starting from v0.17.2, plus a CycloneDX software bill of materials. The installer can verify attestations with --verify-attestation. That is more than many small open-source tools offer, and it is worth using.

Sandboxed agents. Hacker News user quinncom reported running Plannotator with the Pi agent inside the nono.sh sandbox, which needed PLANNOTATOR_REMOTE=1 and an allowance for local port 19432 (comment). That is one user's report, not documentation. It shows the tool can sit inside a locked-down setup if you open the right port.

The tool itself is not an agent-security product. It reviews what an agent proposes. If your worry is what an agent does after you approve, you still need sandboxing and permission controls.

What are developers saying?

The Show HN thread is small, with a handful of comments at the time of writing. User NicoJuicy said they had been using Plannotator since someone from Cloudflare mentioned it on X, and called it "really nice" (comment). User quinncom reported getting it working with Pi, as described above. There was no sign of a critical thread or a benchmark. Treat the praise as early user sentiment, not a verified quality measure.

The star count tells a similar story. At roughly 10,000 stars with 99 open issues and 96 open pull requests on the README page, the project is popular and moving fast, which also means the surface area changes often. Pin a version with --version if you rely on it.

How does it compare with plan mode and other review habits?

Two runners passing a baton, a picture of the handoff between agent and reviewer in an agent plan review workflow

The value is highest at the plan step. Fixing a wrong assumption in a plan costs seconds. Fixing it after the agent has edited twenty files costs a review cycle. That matches the logic behind loop engineering for coding agents, where checkpoints sit inside the loop instead of at the end.

If you run agents unattended, compare this with Agent Autoloop's approval cards, which handles approvals from a background hub. Plannotator is the richer reading surface, Autoloop is the scheduler. If you are choosing an agent in the first place, see our Codex vs Claude Code comparison.

A practical way to try it this week

1. Install the Claude Code plugin or the pinned binary, not the latest script, in a throwaway repository.
2. Ask your agent for a plan to add a small feature, and let Plannotator open the plan view.
3. Add two inline comments and one deletion, then send the feedback back. Check that the revised plan reflects each one.
4. Run /plannotator-review on the resulting diff and compare what you catch there with what you would have caught in the terminal.
5. Set PLANNOTATOR_SHARE=disabled unless you have a reason to share links.
6. Decide after a week of real use. If you approve plans in under ten seconds anyway, the tool will not change your habits.

What this means for what you build and pay

Plannotator costs nothing for the local app, so the price you pay is attention and trust. The tool adds a step to every plan, which only helps if you use that step to think. The hosted Workspaces layer has no published pricing, and the README says its data handling differs from the local app, so ask before putting client code through it.

For teams, the lasting lesson is the pattern, not the product. Put a structured review at the plan step, store the feedback, and make approval something that takes effort. Whether you use Plannotator, a plan-mode habit or a script of your own, the review surface decides how much of the agent's output you really read.

Related reading

• Claude Code plan mode: complete guide
• Claude Code commands reference
• Addy Osmani on cognitive surrender
• AI brain fry and the git queue
• Agent Autoloop approval cards
• Codex vs Claude Code
• What are agent skills?

Official sources: the Plannotator repository, the Plannotator site and its security page, and the Show HN thread.

Star counts, versions and README details are accurate as of November 13, 2026. Check the repository for current releases before you install.