GO TO A SECTION

↑ ↓ to navigate · Enter to openExplore all sections →
FDEInterviews logo

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.

Review the plan where a mistake is cheapestAgent drafts a plan: Plan mode: reads code, proposes steps.. calls ExitPlanMode. Deterministic gate: Our hook: files, tests, rollback named? Forbidden steps absent?. complete. Plannotator review: Browser on a random local port. Strike, replace, comment. Hook waits up to 4 days.. deny + reasons. deny + your notes. approve. Agent implements: Leaves plan mode with the approved plan.. Tool-call hooks: Block writes to protected paths, risky commands and secrets at the moment of the call.. Tests and CI: Fail the change when a rule is broken, whatever the plan said.. Plan feedback reaches the model as text in a denial message. It is guidance the model should follow, not a constraint it cannot break. Review the plan where a mistake is cheapest Claude Code plan mode with a deterministic gate and Plannotator on the ExitPlanMode hook. Enforcement stays in hooks and CI. Agent drafts a plan Plan mode: reads code, proposes steps. calls ExitPlanMode Deterministic gate Our hook: files, tests, rollback named? Forbidden steps absent? complete Plannotator review Browser on a random local port. Strike, replace, comment. Hook waits up to 4 days. deny + reasons deny + your notes approve Agent implements Leaves plan mode with the approved plan. WHAT ACTUALLY ENFORCES RULES Tool-call hooks Block writes to protected paths, risky commands and secrets at the moment of the call. Tests and CI Fail the change when a rule is broken, whatever the plan said. Plan feedback reaches the model as text in a denial message. It is guidance the model should follow, not a constraint it cannot break.
  1. Claude Code calls its ExitPlanMode tool when it wants to start implementing.
  2. A PermissionRequest hook matched to ExitPlanMode runs plannotator. The plan text arrives on standard input as JSON, in tool_input.plan.
  3. Plannotator starts a server on a random local port and opens the review in your browser.
  4. On Approve, it prints {"hookSpecificOutput":{"decision":{"behavior":"allow"}}} and the agent proceeds.
  5. On Send Feedback, it prints a deny decision with a message containing 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 wantPlan review gives youEnforce it with
"Do not touch the migrations folder"A note the model should followA tool-call hook that blocks writes to that path, or a CI check
"Every change needs tests"A comment asking for testsCI that fails without them
"Use the existing retry helper"A suggested replacementCode review on the diff, or a lint rule
"Agree the approach before coding"Exactly this, with historyNothing 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.

python
#!/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)DecisionWhy
"Add retry with backoff to client.py. Unit tests in test_client.py ... Roll back by reverting the commit."allowNames files, tests and rollback
"Speed up CI: skip the flaky integration suite and edit migrations/0042_users.sql to drop the unused column."denyRewrites a migration, disables a check, no tests, no rollback
"Refactor the billing module for clarity."denyNo files, tests or rollback
"Refactor billing.py. Tests: none needed. Rollback: not applicable."allowKeyword 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:

What stays on the machine, and what can leavePlans and annotations: Served from a local port; drafts in the data folder.. Plan history and diffs: Versions kept per project for comparison.. Hook decisions: allow or deny, printed to the agent that ran the hook.. Daily ping: ON by default: Version, age bucket, tool. No ID. Off: NO_ANON_PING=1.. Share links: on click: Small in the link; large encrypted, 7 days. Bearer link.. Notion, Ask AI: if set up: Content to the service or model provider you configure.. Turn sharing off: PLANNOTATOR_SHARE=disabled. Anyone with a full share link can read the plan. On customer engagements, set both opt-outs in the environment before the first run. What stays on the machine, and what can leave Plannotator at commit 26ea4f3, from its README and docs. Read before installing on a customer laptop. STAYS LOCAL BY DEFAULT Plans and annotations Served from a local port; drafts in the data folder. Plan history and diffs Versions kept per project for comparison. Hook decisions allow or deny, printed to the agent that ran the hook. LEAVES THE MACHINE Daily ping: ON by default Version, age bucket, tool. No ID. Off: NO_ANON_PING=1. Share links: on click Small in the link; large encrypted, 7 days. Bearer link. Notion, Ask AI: if set up Content to the service or model provider you configure. Turn sharing off PLANNOTATOR_SHARE=disabled Anyone with a full share link can read the plan. On customer engagements, set both opt-outs in the environment before the first run.
PathDefaultWhat is sentHow to turn it off
Daily anonymous pingOn in release buildsAt 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 addressNO_ANON_PING=1; also off in CI
Share linksOn when you click ShareSmall plans are encoded in the link itself; large ones are encrypted and uploaded, expiring after 7 days. Anyone with the full link can read itPLANNOTATOR_SHARE=disabled, or PLANNOTATOR_SHARE_URL for a self-hosted portal
Notion and other note integrationsOff until configuredThe plan, to your workspaceDo not configure them
Ask AI and AI reviewOff until a provider is chosenSelected content, to that providerDo 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

ProsCons
A real review surface for plans, with versions and diffsA deleted step is guidance to the model, not enforcement
Works with most major coding agents through hooks, plugins and MCPAnonymous daily ping on by default, no in-app notice
Local server; plans stay on the machine unless you shareShare links are bearer links: whoever has one can read it
Dual MIT or Apache-2.0 license, very active projectLarge surface area: Inbox, routines, workspaces, integrations to vet
The hook protocol is simple enough to extend with your own gatesReview 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.

PRACTICE THIS

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.

Discussion (4)

James BennettEditor

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.

Hannah BryantEditor

Reader question: our security team will ask about the share links. Is a link to an encrypted upload safe to paste into a ticket?

Brandon FosterEditor

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.

Arjun MehtaEditor

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.