Plannotator Explained: The Visual Review Layer for AI Coding Agents

If you have used Claude Code, OpenCode, or any CLI coding agent on a non-trivial project, you know this exact scenario:

You give the agent an intricate assignment: “Refactor the auth module to support WebAuthn passkeys alongside JWT, maintaining full backwards compatibility”.

The agent enters Plan Mode and streams a 150-line markdown plan inside your terminal. It details each file it intends to modify, each database schema change, and pauses on a single prompt:

Do you want to proceed with this plan? (y/n)

This is where the workflow stalls. Pressing y without thorough review is risky: if step 3 miscalculates a Redis session lifecycle or step 6 deletes a shared helper, your codebase breaks. But pressing n or typing feedback into the terminal is equally frustrating. You end up drafting awkward command line instructions: “In step 3 do not use an external dependency, rewrite the verify helper in utils.ts following the existing pattern…”. By the time you finish typing, manually editing the code would have been faster.

backnotprop/plannotator targets this operational bottleneck. Rather than modifying model intelligence, it re-engineers how humans supervise agents during planning.

TL;DR

Fast Breakdown:

• What is Plannotator? An open-source, local-first review layer that automatically intercepts an AI coding agent before execution, opening a web canvas for visual redlining.
• Mouse-Driven Plan Corrections: Instead of typing cumbersome descriptions in terminal text, Plannotator launches a browser interface where you highlight bad assumptions, strike out unneeded steps, and attach inline comments directly to the relevant line.
• Non-Blocking Execution (Claude Code 2.1.287+): Frees your terminal. The agent terminates its current conversational turn cleanly rather than freezing the subshell, letting you inspect the plan at your own pace without session timeouts.
• Multi-VCS & Agent Ecosystem: Integrates with Claude Code, OpenCode, Codex, and MCP; supports Git, GitButler, Jujutsu (jj), and Perforce (p4).
• Repository: backnotprop/plannotator on GitHub (Apache 2.0 / MIT).

---

The Mental Model: Terminals Stream Logs, Browsers Review Plans

The architectural mismatch is straightforward: Terminals were built to run commands and stream log outputs. They were never designed for human beings to read, critique, and annotate complex multi-step architecture plans.

When an autonomous agent outlines a 10-step refactoring plan touching 6 files, you need visual markup: striking out superfluous steps, flagging delicate migrations, and attaching notes inline. Keyboard navigation and monochrome terminal text cannot match that bandwidth.

Plannotator intercepts this exact handoff:

---

Hands-On Reality: From Terminal Text to Visual Redlining

Plannotator does not modify underlying LLM weights. It hooks directly into the agent event loop.

1. Intercepting ExitPlanMode

In Claude Code, when the model completes its analysis and prepares to apply changes to files, it triggers an internal tool named ExitPlanMode.

Plannotator registers a hook that catches this event:

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "plannotator",
            "timeout": 345600
          }
        ]
      }
    ]
  }
}

The moment Claude signals an intention to leave Plan Mode, the hook takes over:

1. It reads the markdown plan from standard input (stdin).
2. It spins up an ephemeral local HTTP server (selecting a random port by default).
3. It launches a browser tab or an internal VS Code webview.

Instead of an unyielding y/n prompt, you get an interactive document:

• Want to omit step 5? Select the step and click strike-through.
• Step 7 uses the wrong schema? Highlight the phrase, type an inline note: “Use user_id column instead of account_id”.
• Ready? Click Send Feedback. Plannotator serializes your annotations into structured prompt context, injects it back to the agent, and Claude regenerates the plan accordingly without requiring manual text coordination.

2. Non-Blocking Execution in Claude Code 2.1.287+

Historically, when a CLI hook intercepted a command, it blocked the subshell. The agent remained locked in an active wait state. If the plan was complex and you stepped away for 15 minutes, your shell remained frozen. Any network hiccup risked dropping the session.

Beginning with Claude Code 2.1.287+, Plannotator enables an asynchronous non-blocking workflow by default (disableable via PLANNOTATOR_CLAUDE_MOD=0):

• Clean Turn Termination: Instead of freezing Claude Code in a synchronous wait loop, the hook instructs Claude to end its current conversational turn immediately.
• Unconstrained Terminal: Your shell is free. You can run git commands, run tests, or close your laptop.
• Resume as Next Turn: When you complete your review on the browser and click “Approve”, Plannotator delivers your approval as the next user turn. Claude resumes, ingests the annotations, and executes without shell lockup.

3. Plannotator Inbox: Aggregating Multi-Agent Workflows

A major feature of the project is Plannotator Inbox.

When running multiple agents concurrently (such as Claude Code handling backend refactoring while OpenCode writes integration tests), running plannotator inbox mcp turns Plannotator into an MCP server. Any agent requiring user sign-off or diff inspection can route requests into a single local queue. You review decisions sequentially in one browser tab rather than toggling across separate terminal windows.

---

Production Gotchas & Operational Traps

Deploying Plannotator in real workflows reveals two operational traps and one critical security consideration:

1. SECURITY ADVISORY: Remote Mode Over SSH and Docker

When developing on a remote VM or inside a headless Docker container without a display server, the default browser opener (xdg-open or open) fails. You can switch to remote mode:

export PLANNOTATOR_REMOTE=1
export PLANNOTATOR_PORT=19432
export PLANNOTATOR_BROWSER=none

CRITICAL SECURITY REQUIREMENT:
When PLANNOTATOR_REMOTE=1 is set, Plannotator binds to 0.0.0.0 with zero authentication. Anyone who can route network packets to port 19432 can inspect your code plans and inject feedback directly into your agent.
Mandatory Hardening: Never expose port 19432 on a public firewall or cloud security group. Always restrict access via a local SSH tunnel:

ssh -L 19432:localhost:19432 user@remote-server

Alternatively, isolate access within a private Tailscale network.

2. The Over-Annotation Token Trap

An interactive visual canvas often tempts developers into micromanagement: fixing punctuation, debating variable names, or tweaking formatting.

Remember: Every annotated comment is injected into the model context window as natural language instruction. Leaving dozens of minor comments consumes significant context tokens and dilutes model attention away from high-stakes architectural changes. Focus your annotations on critical paths: schema integrity, migrations, security boundaries, and edge cases. Let automated linters handle code style.

---

Setup in 2 Minutes

Install the standalone binary (the installer automatically detects Claude Code and sets up the hook):

# Install standalone binary
curl -fsSL https://plannotator.ai/install.sh | bash

To install manually through the Claude Code plugin manager:

/plugin marketplace add backnotprop/plannotator
/plugin install plannotator@plannotator

Once installed, work with Claude Code as usual. The next time a prompt triggers Plan Mode, the visual review tab launches automatically.

---

Final Take

Tools like Plannotator highlight a key evolution in software development: Once AI code generation crosses baseline competence, developer productivity is bounded not by model generation speed, but by the cognitive overhead of human review.

Let the terminal execute commands and stream logs, and let a dedicated visual interface handle the high-bandwidth task of reviewing architectural plans.

---

FAQ

1. Are plans and code sent to external servers?

By default, Plannotator provides optional team sharing via room.plannotator.ai. For proprietary codebases where external network transmission is prohibited, disable sharing entirely:

export PLANNOTATOR_SHARE=disabled

Additionally, note that application startup checks GitHub for new releases, URL annotations query Jina, and the “Ask AI” feature sends context to your configured LLM provider.

2. Can Plannotator review actual code diffs?

Yes. Beyond intercepting ExitPlanMode for markdown plans, Plannotator provides a side-by-side diff viewer with support for Git, GitButler, Jujutsu (jj), and Perforce (p4).

3. How do I reopen a previous review session?

To list previous review sessions, run:

plannotator sessions
# Or open session number N directly:
plannotator sessions --open <N>

Within Claude Code, /plannotator-last requests review of the agent’s most recent message.