Independent AI intelligence Two editions daily · ET
Fervor AI

Analysis · November 15, 2026 · repo

PlannotatorClaude CodeCodexclaude-codecodexagent-harnessai-skills

Plannotator Turns Your Coding Agent's Plan Into a Document You Can Mark Up

Review the plan with a red pen before the agent writes a line, then check what it sends off your machine.

Coding agents have gotten good at writing code. They're still mediocre at writing the right code, and the cheapest moment to fix that is before they start.

Most of us review at the wrong end. The agent proposes a plan in a wall of terminal text, we skim it, type "looks good," and then spend twenty minutes reading a diff that went somewhere we didn't want. Feedback on a plan is cheap. Feedback on 600 changed lines is expensive, and by then the agent has committed to a shape.

Plannotator, an open-source tool that was #8 on Trendshift's live GitHub board on Sunday afternoon, moves the review to the cheap end. When your agent proposes a plan, Plannotator opens it in your browser as a document. You highlight lines, comment, suggest changes, and press send. Your markup goes back to the agent as its next message.

That is the shift worth taking from it: the plan is the steering wheel, and the diff is the rear-view mirror. A tool that makes plans pleasant to mark up changes where you spend your attention.

Here is what it does, how to try it in ten minutes, and the network behavior you should know before you point it at anything sensitive.

What Plannotator is

Plannotator calls itself "a local, browser-based review surface for AI coding agents." In plain terms, it is a small program on your machine that opens a review page in your browser whenever your agent has something for you to look at.

It plugs into the agent through each tool's own extension points: plugins, hooks (scripts a coding agent runs at set moments, like right after it drafts a plan) and slash commands. The README lists Claude Code, Codex, Copilot CLI, Gemini CLI, OpenCode, Kiro, Droid, Amp, DeepSeek Harness and Pi.

It has three main surfaces:

  • Plan review. No command needed. When the agent creates a plan in plan mode, the review page opens on its own.
  • Annotate. Mark up any markdown file, folder, URL or rendered HTML, or the agent's last message, and send notes back.
  • Code review. Comment on local changes or a GitHub pull request or GitLab merge request, and your comments go back to the agent. It works with Git, GitButler, Jujutsu and Perforce.

There is also a newer Inbox, one local window where several agents can leave you questions and files while they keep working. You answer when you have a minute, and each reply goes back to the session that asked.

The project ships fast. The latest release when this was written, v0.28.65, landed on the evening of November 14 (US Eastern), and shields.io showed about 12,000 stars on November 15. The README says it is dual-licensed under Apache-2.0 or MIT; the MIT license file is in the repo.

Why marking up a plan beats approving it

Think about how you review a colleague's design doc. You don't reply "approved" or "rejected." You circle the paragraph that worries you and write "why not reuse the existing queue here?" in the margin.

Terminal plan approval gives you two buttons. Plannotator gives you a margin.

That changes the quality of feedback in a specific way. Line-level comments tell the agent exactly which step to change and leave the rest alone. "Redo the plan but don't touch the database" is a sentence an agent can misread. A comment pinned to step 4 that says "use the existing migration, don't write a new one" is hard to misread.

It also changes timing, at least on Claude Code. The README says that on Claude Code 2.1.287 or newer, plan review, code review and annotate "don't make Claude wait": Claude ends its turn and your decision arrives later as a message. So you are not holding a session hostage while you think. (Set PLANNOTATOR_CLAUDE_MOD=0 to go back to the classic blocking flow.)

My take after reading the README: the plan-review hook is the part that earns its place. The Inbox is promising but younger, and a lot of the surface area beyond plan review is optional. Start with plans.

Put this into practice

The quickest path is the installer, which drops the plannotator binary in place, detects your installed agents and wires up hooks and commands for each (install section).

# macOS / Linux / WSL
curl -fsSL https://plannotator.ai/install.sh | bash

If you would rather not have an installer touch every agent's config, there is a binary-only mode that skips all hooks, skills and slash commands:

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

Then finish for your agent. Two common cases:

  • Claude Code: run /plugin marketplace add backnotprop/plannotator, then /plugin install plannotator@plannotator, and restart Claude Code.
  • Codex: nothing extra. Plan review turns on through Codex's experimental Stop hook on macOS, Linux and WSL, and the $plannotator-review, $plannotator-annotate and $plannotator-last skills come with it. On Codex, slash commands become !plannotator ….

Now try it on a real task. Ask your agent for something with a few moving parts, like "add rate limiting to the login endpoint," and let it enter plan mode. The review page should open in your browser. Leave at least two comments pinned to specific steps, one that changes an approach and one that rules something out, and send. Watch whether the agent's next plan changes only what you marked. That single test tells you whether this workflow fits you.

Three commands worth knowing after that:

/plannotator-review                    # review uncommitted changes
/plannotator-annotate README.md        # mark up a file and send notes back
plannotator archive                    # browse saved plan decisions

The archive is more useful than it sounds. It keeps a record of the plans you approved and what you said about them, which is a decent answer to "why did the agent do it this way?" two weeks later. (It is also data that piles up on disk forever; more on that below.)

Know what leaves your machine

This is the part most people skip, and it is where the project's own documents disagree with each other, so read both.

The content baseline is good. The README's Privacy and network behavior section and the privacy policy agree that plans, documents, diffs, annotations, drafts, history and configuration stay on your machine by default.

They disagree on usage data. The README says Plannotator "does not collect usage telemetry or analytics." The privacy policy, last updated November 9, says the opposite in its first line: each Plannotator tool you use sends "one anonymous ping a day" to ping.plannotator.ai, on by default, up to five a day per computer. The policy shows the whole message (version, a rough weeks-since-first-use bucket, which tool ran, and your chosen favicon), says it carries no ID, file names or content, and says the server keeps only daily totals. It is a small, well-documented count. It is still telemetry, and the README on GitHub says there is none. Set NO_ANON_PING=1 in the environment Plannotator runs in to turn it off.

The other exceptions are specific, and you should read them before reviewing anything under NDA:

  • Release checks. Plannotator asks GitHub whether a newer release exists. No plan content goes with it, but GitHub sees a request. The README says there is currently no opt-out; the privacy policy says you can turn it off with PLANNOTATOR_UPDATE_CHECK=0 or { "updateCheck": false } in ~/.plannotator/config.json. Set it, then watch your network log to confirm which document matches the build you run.
  • Git remote checks. Local code review may run git ls-remote against your origin to find the default branch. It doesn't send your diff, and you can turn it off with plannotator review --no-git-remote-check, PLANNOTATOR_GIT_REMOTE_CHECK=0, or "gitRemoteCheck": false in ~/.plannotator/config.json.
  • URL annotation fetches the page through Jina Reader, a third-party page-reading service, by default for public pages.
  • Ask AI and AI review agents send your question plus the relevant plan, document, repository or diff context to whatever model provider you configured.
  • Sharing. Small shares are compressed into the link itself, which is not encrypted, so anyone with the full link can read them. Larger shares are encrypted before upload and expire after 7 days. You can switch sharing off completely with PLANNOTATOR_SHARE=disabled.
  • Workspaces, the team-sharing direction, is a separate hosted product with a waitlist, so the local-storage promise doesn't cover content you put there.
  • The feedback archive stays local, but the policy says it is on by default and nothing prunes it: every plan decision and review you submit is kept under ~/.plannotator/feedback/ until you delete it. Set PLANNOTATOR_FEEDBACK_HISTORY=0 if you'd rather it not exist.

A practical setup for sensitive repos: install with --minimal and add only your agent's plugin, set NO_ANON_PING=1, PLANNOTATOR_UPDATE_CHECK=0 and PLANNOTATOR_SHARE=disabled, turn off the Git remote check, and don't use Ask AI or URL annotation on private material. Put the environment variables in the shell profile that launches your agent (for example ~/.zshrc), since Plannotator reads the environment it runs in, then restart the agent. You keep plan review and lose very little.

Honest limitations

It adds a browser tab to your loop. If you live entirely in the terminal, that context switch is real; the project offers Herdr Annotate and a standalone TUI for terminal-only review, but the main experience is the browser.

Support is uneven across agents. Droid gets commands only, with no plan interception yet. Codex's plan review rides on a hook the README itself calls experimental, and on native Windows the installer prints manual steps instead. Check your agent's row in the install table before assuming parity.

The installer does a lot. A full install can contact GitHub, a sidecar project and npm, and it edits several agents' config files. That is convenient and also a lot of surface to hand a curl | bash. The --minimal flag exists for a reason.

It changes fast. A version number like v0.28.65 tells you the team ships constantly. That is good for fixes and means the README you read today may describe behavior that moved by next month. Re-read the privacy section after updates.

And it can't fix a bad plan you don't read. Plannotator makes review easier. It doesn't make it happen.

Where to start

Pick one agent you already use, install Plannotator in minimal mode plus that agent's plugin, and run three real tasks through plan review this week. Count how many diffs you end up rewriting compared to last week.

If the number drops, keep it and look at the Inbox next. If it doesn't, you have lost an afternoon and learned something useful about where your agent actually goes wrong.

Either way, the habit sticks: argue with the plan, not the diff.

Sources: backnotprop/plannotator README (read November 15, 2026, at release v0.28.65); Plannotator privacy policy (last updated November 9, 2026); Plannotator releases; Trendshift live board (read about 15:15 ET, November 15, 2026). Star count from shields.io on November 15, 2026.