Companion to the hands-on tutorial: Review your agent’s plans and diffs with Plannotator on Cui.Guru. The tutorial shows how to use it. This post explains why it is built this way.
backnotprop/plannotator (about 13.5k stars per the GitHub API on 2026-11-19, Apache 2.0, TypeScript) is described as a local, browser-based review surface for AI coding agents. I cloned it and read apps/hook/server/index.ts, apps/hook/server/claude-plan.ts and packages/server/index.ts. The repo is large (apps for many agents, plus an Inbox); I followed one thread: what happens between the agent proposing a plan and the agent hearing your verdict.
Scope: this article follows the classic PermissionRequest flow. The README says that on Claude Code 2.1.287 or newer, review does not make Claude wait: Claude ends its turn and your decision arrives later as a message (set PLANNOTATOR_CLAUDE_MOD=0 for the classic flow; the detached path lives in claude-mod-plan.ts). The review surface and decision object are the same in both; only the delivery differs.
The workflow in motion
Architecture
The README’s own summary of plan review is a chain: the agent calls ExitPlanMode, the PermissionRequest hook fires, a local server reads the plan from the hook input, the browser opens, you approve or deny, and a denial returns structured feedback. In the source, apps/hook/ is the CLI entry that speaks each harness’s hook protocol, while packages/server/ holds the HTTP server and UI-facing endpoints. AGENTS.md states a rule that shapes the design: endpoint changes go into both the Bun server (packages/server/) and the Pi server (apps/pi-extension/server/), with shared logic in packages/shared/.
The decision itself is small. Each harness gets a different output format, but they all consume the same result object.
The core design idea
The key idea is a parked promise. The server creates decisionPromise, and the approve and deny endpoints call resolveDecision (see packages/server/index.ts, around the resolveDecision and decisionPromise declarations). The hook process just awaits it, which is why the agent is blocked until you answer.
// apps/hook/server/index.ts
// Wait for user decision (blocks until approve/deny)
const result = await server.waitForDecision();
The approve endpoint archives the decision, deletes the draft, then resolves:
// packages/server/index.ts
decisionSettled = true;
resolveDecision({ approved: true, feedback, savedPath, agentSwitch, permissionMode: effectivePermissionMode });
A deny resolves with approved: false and the feedback text. The adapter then turns that into the harness’s format. For Claude Code the deny becomes a PermissionRequest decision with behavior: "deny" and a composed message that carries your feedback (or “Plan changes requested” when empty).
Two details show the care taken. First, a comment in the allow branch explains that Claude Code 2.1.199 and later silently drops an allow for ExitPlanMode when updatedInput is absent, so Plannotator echoes the tool input and carries the reviewed plan:
updatedInput: { ...event.tool_input, plan: planContent },
Second, claude-plan.ts handles a stale-plan race (its header notes Claude Code 2.1.285 fixed this on its side; older versions still need it). Claude Code fills plan before the tools in the message run, so if the model edits the plan file and calls ExitPlanMode in one message, the inline plan can be the pre-edit version. The resolver prefers the plan file, but only if it passes a gate:
// apps/hook/server/claude-plan.ts
if (!isAbsoluteUserPath(planFilePath) || !/\.md$/i.test(planFilePath)) return inlinePlan;
...
if (!stat.isFile() || stat.size > MAX_ANNOTATABLE_FILE_BYTES) return inlinePlan;
return readFileSync(path, "utf8") || inlinePlan;
An absolute .md path, a regular file, under a size cap, else fall back to the inline plan. The file comment says this keeps a FIFO, device or directory from hanging the hook.
Takeaways
- Human-in-the-loop is easiest as a blocking hook: the process boundary does the waiting for you.
- One result shape, many output adapters: harness differences stay at the edge.
- Defend the hook against hostile or odd inputs (path gate, size cap, fallback) because it runs on every plan.
- Treat host quirks as documented code comments; the
updatedInputnote is the kind that saves the next maintainer.
Work with me
Want a human review step wired into your own agent workflow? Get in touch.
Click to load Disqus comments