Free guide

Plannotator: Mark Up Your Coding Agent's Plan Before It Writes Code

An open-source review screen for your coding agent's plans. What it does, how it works, how to install it without letting it touch every agent you have, and the fine print.

By Beau Johnson·
The Short this guide goes with: Plannotator: Mark Up Your Coding Agent's Plan Before It Writes Code

Quick answer

Plannotator is an open-source tool (MIT or Apache 2.0) that opens your coding agent's plan in your browser so you can highlight lines, comment, delete or approve, then sends your notes back to the agent as structured feedback tied to each line. With its Claude Code plugin it catches the plan when Claude tries to leave plan mode. Install just the program with the --minimal flag, then add the one plugin you want.

The short version

  • Plannotator is a local, browser-based review screen for coding agents like Claude Code, Codex, Copilot CLI and Gemini CLI. It's trending on GitHub with over 13,000 stars.
  • When Claude Code tries to leave plan mode, its plugin opens the plan in your browser. You mark it up like a doc and your notes go back to the agent with the line they're about.
  • The default installer wires itself into every agent it finds. The --minimal install puts only the program on your machine, and you add the plugin you want.

How it actually works

A red pen for the blueprint

Answering a long plan with a quick OK is like signing a blueprint you never unrolled. Plannotator unrolls it: the plan shows up as a clean page in your browser, and you can highlight any line and comment on it, delete it, label it or give it a thumbs-up, plus leave a general comment or add images.

It catches the plan at the door

The Claude Code plugin adds a hook that fires when Claude tries to leave plan mode. A small server on your own computer reads the plan from that hook and opens the review page. Approve it and Claude goes ahead. Send feedback and Claude revises, and the next version shows what changed. Plan review needs no command; it opens by itself the next time your agent proposes a plan.

Your note lands on the exact line

We tried it in a sandbox on a made-up plan (add dark mode to a settings page). The test highlighted step four, "Swap every hard-coded hex colour in styles/ for CSS variables", and left one note: "140 files is too much for one PR. Do the header + buttons first, rest in a follow-up." Plannotator turned that into markdown feedback: "## 1. (line 10) Feedback on:" with the step quoted and the note under it. That's the format your agent would get back, instead of a paragraph it has to match to the plan. In our run no agent was attached, so it printed in the terminal.

Claude doesn't have to sit and wait

On Claude Code 2.1.287 or newer, plan review doesn't make Claude wait: Claude ends its turn and your decision arrives later as a message. Set PLANNOTATOR_CLAUDE_MOD=0 if you want the classic flow back.

How to set it up

  1. 1.Install only the program

    The --minimal flag installs just the plannotator binary to ~/.local/bin and skips every skill, hook, slash command and per-agent config. Read install.sh first if you like; it's a curl | bash installer. Windows PowerShell has its own installer in the README.

    curl -fsSL https://plannotator.ai/install.sh | bash -s -- --minimal
  2. 2.Try it on any file, no agent needed

    Point it at a markdown file. It starts a local session and opens the review page in your browser. Mark something up and send feedback to see what your agent would get.

    plannotator annotate plan.md
  3. 3.Add the Claude Code plugin

    Inside Claude Code, add the marketplace and install the plugin, then restart Claude Code. Using Codex, Copilot CLI or another agent? The README has one line per agent.

    /plugin marketplace add backnotprop/plannotator
    /plugin install plannotator@plannotator
  4. 4.Turn on plan mode and ask for a plan

    Press Shift+Tab until Claude Code is in plan mode and ask for a change. When Claude tries to leave plan mode, the plan opens in your browser. Highlight the line you'd change, add your note, and send it, or approve it.

  5. 5.Switch off the daily ping if you want

    Plannotator sends one anonymous ping a day for each of its tools you use. Set this in your shell profile to turn it off. PLANNOTATOR_SHARE=disabled turns off share links too.

    export NO_ANON_PING=1

The fine print

  • Dual-licensed MIT or Apache 2.0, your choice, so companies can use it too. Keep the license notices.
  • The default installer (curl | bash with no flags) auto-detects your coding agents and adds hooks, skills and slash commands to each one. Use --minimal if you only want one.
  • One anonymous ping a day for each tool you use (tool, version, weeks since first use, no ID). Turn it off with NO_ANON_PING=1. It also checks GitHub for updates (PLANNOTATOR_UPDATE_CHECK=0 turns that off).
  • Remote mode listens on every network interface with no login, so keep that port closed to networks you don't trust.
  • It moves fast: 13 releases between November 9 and 18 (v0.29.0 on Nov 18), almost all of it by one developer, Michael Ramos.
  • Our own run used the program and the annotate command in a sandbox. We didn't test the Claude Code plugin with a real Claude session.

FAQ

What is Plannotator?

A local, browser-based review screen for AI coding agents. When your agent proposes a plan or a decision, or finishes working, Plannotator opens it in your browser so you can mark it up and send the feedback back to the agent.

Is Plannotator free?

Yes. It's open source under MIT or Apache 2.0, your choice, which allows commercial use. The repo is on GitHub at backnotprop/plannotator.

Does Plannotator work with Codex and other agents?

Yes. The README lists Claude Code, Codex, Copilot CLI, Gemini CLI, Kiro, Droid, Amp, Pi and more, with an install line for each. With the default installer, Codex plan review runs through Codex's experimental Stop hook.

Does Plannotator send my plans anywhere?

Plans stay on your own computer by default. It sends an anonymous daily ping per tool (off with NO_ANON_PING=1) and checks GitHub for updates. Ask AI and review agents send context to the AI provider you pick, only when you use them (PLANNOTATOR_AI=disabled turns them off). Markdown share links upload only when you click Create short link (encrypted, deleted after 7 days); small shares live inside the link, so anyone with the link can read them. PLANNOTATOR_SHARE=disabled turns sharing off.

How do I install Plannotator without changing all my agents?

Run the installer with --minimal: curl -fsSL https://plannotator.ai/install.sh | bash -s -- --minimal. That installs only the program. Then add just the plugin you want, like /plugin install plannotator@plannotator in Claude Code.

Sources

Facts checked 2026-11-19 against the Plannotator README, hooks.json, LICENSE files, the v0.29.0 release, plannotator.ai/privacy, the GitHub API (13,542 stars) and our own sandbox run of v0.28.67 on 2026-11-18.

Want help building with tools like this?

Join the Shipping Skool community free. Paid members get live bootcamp calls every week and weekly-updated courses.

Join Shipping Skool

More free guides