Plannotator Review: Annotating a Coding Agent's Plan Before It Writes Code, and What Leaves Your Machine
Plannotator turns a Claude Code, Codex or Gemini CLI plan into a browser review you can annotate, then sends your notes back to the agent. How the plan hook works, what it cannot enforce, what it sends off the machine by default, and a deterministic plan gate you can add today.
BY BRANDON FOSTER · FDEINTERVIEWS EDITORIAL · UPDATED NOVEMBER 19, 2026 · 7 MIN READ
PRACTICE THIS:When to trust and when to review AI pull requests ·Design a plan, code, test, fix agent system ·Harness engineering for coding agents ·Coding and AI-first engineering questions
Plannotator moves the review of an AI coding agent's plan out of the terminal and into a browser page you can mark up, then sends your markup back to the agent before it writes any code. For Claude Code it hooks the moment the agent leaves plan mode. The plan opens locally; you strike, replace or comment on lines; Approve lets the agent proceed, and Send Feedback returns your notes and keeps it planning. We read the source at commit 26ea4f3 (19 November 2026). Three things the launch posts do not mention: a deleted step is advice to the model, not a rule it must obey; release builds send one anonymous ping a day unless you opt out; and share links are readable by anyone who has them. Our recommendation: use it for plans that are expensive to get wrong, put a cheap deterministic gate in front of it, and switch off sharing on customer machines.
The problem it solves
The usual loop with a coding agent goes like this. The agent writes a long Markdown plan, you skim it in the terminal, approve, and twenty minutes later find it misread a requirement or picked an architecture you did not want. The plan was the cheapest place to catch that, and a wall of terminal text is a poor place to read it. Plannotator gives the plan the same treatment a pull request gets: inline comments, suggested replacements, deletions, a diff between plan versions, and one decision at the end.
It is popular for a reason. The repository, created on 28 December 2025, had about 13,600 stars when we checked. It supports Claude Code, Codex, Copilot CLI, Gemini CLI, OpenCode, Kiro, Droid, Amp, DeepSeek Harness and Pi, and has grown well past plans: code review of local diffs and pull requests, annotation of HTML artifacts and live local sites, and an Inbox where several agents leave questions while they work.
How the Claude Code hook works
The integration is a few lines of hook configuration, and it is worth understanding because you can build on the same mechanism yourself.
- Claude Code calls its
ExitPlanModetool when it wants to start implementing. - A
PermissionRequesthook matched toExitPlanModerunsplannotator. The plan text arrives on standard input as JSON, intool_input.plan. - Plannotator starts a server on a random local port and opens the review in your browser.
- On Approve, it prints
{"hookSpecificOutput":{"decision":{"behavior":"allow"}}}and the agent proceeds. - On Send Feedback, it prints a
denydecision with amessagecontaining your annotations. Claude Code treats the denial as the tool's result, so the model reads your notes and revises the plan without leaving plan mode.
The hook's timeout in the shipped configuration is 345,600 seconds, which is four days. The review waits for you. If the agent process dies first, a watchdog ends the review server within about ten seconds so no orphaned server keeps its port.
What review cannot do: enforce
A reader under one of the launch posts asked the right question: when you delete a step, is it a hard rule or a suggestion? Mechanically, it is a suggestion. Your deletions, replacements and comments become text in the denial message. A model that later decides a step is necessary can reintroduce it, and nothing in plan review will stop it. That is not a flaw in Plannotator. It is what plan review is.
Rules you need enforced belong where violations fail:
| You want | Plan review gives you | Enforce it with |
|---|---|---|
| "Do not touch the migrations folder" | A note the model should follow | A tool-call hook that blocks writes to that path, or a CI check |
| "Every change needs tests" | A comment asking for tests | CI that fails without them |
| "Use the existing retry helper" | A suggested replacement | Code review on the diff, or a lint rule |
| "Agree the approach before coding" | Exactly this, with history | Nothing else does it as well |
A deterministic gate in front of the human
Plannotator's two outputs, allow and deny with a message, are just the hook protocol. You can use the same protocol to send back plans that are missing basics before a person is ever asked to read them. Here is a small gate. We ran it on payloads in the shape the hook receives; we did not run it inside a live Claude Code session.
#!/usr/bin/env python3
"""A deterministic plan gate for Claude Code's ExitPlanMode PermissionRequest hook."""
import json, re, sys
CHECKS = [
("how the change will be tested", r"\btest(s|ing)?\b"),
("how to roll it back", r"\b(roll ?back|revert|undo)\b"),
("which files it will touch", r"\b[\w./-]+\.(py|ts|tsx|js|go|sql|ya?ml|md)\b"),
]
FORBIDDEN = [
("drops or rewrites a migration", r"\b(drop table|delete .*migration|edit .*migrations?/)"),
("disables a check to make it pass", r"\b(skip|disable|xfail|--no-verify)\b"),
]
def decide(payload):
plan = payload.get("tool_input", {}).get("plan", "")
missing = [name for name, rx in CHECKS if not re.search(rx, plan, re.I)]
bad = [name for name, rx in FORBIDDEN if re.search(rx, plan, re.I)]
if not missing and not bad:
return {"hookSpecificOutput": {"hookEventName": "PermissionRequest",
"decision": {"behavior": "allow"}}}
lines = [f"- The plan {n}. Remove that step or justify it." for n in bad]
lines += [f"- The plan does not say {n}." for n in missing]
return {"hookSpecificOutput": {"hookEventName": "PermissionRequest",
"decision": {"behavior": "deny",
"message": "Revise the plan before implementing:\n" + "\n".join(lines)}}}
if __name__ == "__main__":
print(json.dumps(decide(json.load(sys.stdin))))
Four plans, four results:
| Plan text (abridged) | Decision | Why |
|---|---|---|
| "Add retry with backoff to client.py. Unit tests in test_client.py ... Roll back by reverting the commit." | allow | Names files, tests and rollback |
| "Speed up CI: skip the flaky integration suite and edit migrations/0042_users.sql to drop the unused column." | deny | Rewrites a migration, disables a check, no tests, no rollback |
| "Refactor the billing module for clarity." | deny | No files, tests or rollback |
| "Refactor billing.py. Tests: none needed. Rollback: not applicable." | allow | Keyword checks are trivially satisfied |
The last row is the point. A deterministic gate is a floor that saves a person from reading plans that are obviously incomplete. It is not a review, and a plan that says the words without meaning them sails through. Put the gate first and a person second, and keep enforcement in tool-call hooks and CI. If you run both this gate and Plannotator on the same hook, read Claude Code's documentation on how multiple hook decisions combine before relying on the order.
What leaves the machine
The launch posts say Plannotator runs locally and keeps review data on your machine by default. That is accurate for plans and annotations. Before installing it on a customer's machine, know the rest, all of it documented in the repository:
| Path | Default | What is sent | How to turn it off |
|---|---|---|---|
| Daily anonymous ping | On in release builds | At most one request a day per tool, five a day in all: version, install-age bucket, tool name, a first-of-the-day flag and the chosen favicon. No ID; the receiving service stores no IP address | NO_ANON_PING=1; also off in CI |
| Share links | On when you click Share | Small plans are encoded in the link itself; large ones are encrypted and uploaded, expiring after 7 days. Anyone with the full link can read it | PLANNOTATOR_SHARE=disabled, or PLANNOTATOR_SHARE_URL for a self-hosted portal |
| Notion and other note integrations | Off until configured | The plan, to your workspace | Do not configure them |
| Ask AI and AI review | Off until a provider is chosen | Selected content, to that provider | Do not choose a provider |
The project's own docs describe the ping as "on by default with no in-app notice," disclosed in the release notes, the privacy page and the Inbox settings. It is a coarse usage count, not plan content, but a customer's security team will want to know about it before you install anything, and on an engagement you should set the opt-out in the environment before the first run.
Where it fits in an FDE engagement
On a customer engagement, the plan is often the artifact you most need to share: with the customer's tech lead, who knows the system, and with a security reviewer, who knows the rules. Plannotator makes that conversation concrete. It is a poor fit for a fast fix inside a sandbox, where a good test is cheaper than any review. And it does not replace the controls that actually stop an agent: permissions, tool-call hooks and CI. Our harness engineering guide covers how those fit together.
Pros and cons
| Pros | Cons |
|---|---|
| A real review surface for plans, with versions and diffs | A deleted step is guidance to the model, not enforcement |
| Works with most major coding agents through hooks, plugins and MCP | Anonymous daily ping on by default, no in-app notice |
| Local server; plans stay on the machine unless you share | Share links are bearer links: whoever has one can read it |
| Dual MIT or Apache-2.0 license, very active project | Large surface area: Inbox, routines, workspaces, integrations to vet |
| The hook protocol is simple enough to extend with your own gates | Review time is the cost; not worth it for small changes |
What to say about it in an interview
If asked how you would keep a coding agent from building the wrong thing, separate three layers. "I review the plan where a mistake is cheapest, and I make that review easy with a tool like Plannotator. I put a deterministic gate in front so people only read plans that are complete. And I never rely on review for rules: anything that must not happen is blocked by a tool-call hook or fails CI." The interviewer is listening for whether you know which layer is advisory and which one is enforced.
Turn it into offers. Work the real questions and concepts this maps to:
FAQ
Plannotator is an open-source (MIT or Apache-2.0) local review surface for AI coding agents. When an agent such as Claude Code finishes a plan, a hook opens the plan in your browser, where you can comment on, delete or replace parts of it. Your annotations go back to the agent as structured feedback, and it revises the plan before writing code. It also reviews diffs and pull requests and has an Inbox for messages from several agents.
Through a PermissionRequest hook on Claude Code's ExitPlanMode tool. The hook receives the plan text on standard input, serves a review page on a random local port, and replies with allow when you approve or deny with a message when you send feedback. A denial keeps the agent in plan mode and hands it your notes.
Plans and reviews stay local by default, but not everything does. Release builds send one anonymous daily ping, on by default, which NO_ANON_PING turns off. Sharing a plan puts small plans in the link itself and uploads large ones encrypted for 7 days; anyone with the full link can read it, and PLANNOTATOR_SHARE=disabled turns sharing off. Integrations such as Notion and the Ask AI providers send content only when you configure them.
No. The deletion reaches the agent as feedback text in the denial message, which the model should follow but is not forced to. To enforce a rule, such as never editing migrations, add a check that runs on the agent's tool calls or in CI, where a violation fails instead of relying on the model.
Usually not. Review effort pays off when a wrong plan is expensive: changes that touch data, interfaces other teams use, security, or more than a few files. For a one-file fix, a quick read in the terminal and a good test are enough.
Discussion (4)
The four-day hook timeout is a design statement. Plannotator assumes the person might go to lunch, or to sleep, before deciding. That is right for a plan you care about, and it is also why you want a cheap deterministic gate in front of it, so the human queue only gets plans worth a person's time.
Reader question: our security team will ask about the share links. Is a link to an encrypted upload safe to paste into a ticket?
The README's own wording is the answer: anyone with the full link can read it. Treat the link as the secret. For customer code, I would set PLANNOTATOR_SHARE to disabled on engagement machines and share plans through the customer's own review tool instead.
What I like is that the plan becomes an artifact with history. In an incident review you can point at the version the agent proposed, the line someone struck out, and the version it executed. Without that, 'the agent decided' is all anyone has.
