Plannotator: How to Review and Annotate Your Coding Agent’s Plan Before It Writes Code

Plannotator opens your coding agent’s plan in a browser so you can mark it up and send feedback before code gets written. Here is the install, the commands and the privacy fine print.

Reviewed by Mindloop Editorial on . Every link in the Sources section at the end was re-checked that day.

Graphic of a browser window with a marked-up plan and comment bubbles, illustrating the Plannotator tool for reviewing coding agent plans.

Your coding agent just proposed a twelve-step plan and wants a thumbs-up before it starts rewriting your project. You skim it in a terminal, type “looks good,” and hope step nine does not delete something you like.

Plannotator is an open-source tool that swaps the skim for a proper markup session: the plan opens in your browser, you comment on it line by line, and your notes go straight back to the agent. Here is how to set it up and use it before any code gets written.

What you need

  • A supported coding agent. The README names Claude Code, Codex, Copilot CLI, Gemini CLI, OpenCode, Kiro, Droid, Amp and Pi.
  • A terminal and a browser. Plannotator is, in its README’s words, “a local, browser-based review surface.”
  • Git, which Plannotator’s installation docs say the installer needs for skills.

Plannotator is free, dual-licensed under Apache 2.0 or MIT, and as of 15 November 2026 its GitHub repo (backnotprop/plannotator) shows about 11,400 stars. It was created on 28 December 2025, and its latest release, v0.28.65, was published that day. The commands below are copied from its README and docs as of 15 November 2026 and checked against those pages; the shell lines pass a syntax check, but we did not install Plannotator for this article.

Step 1: Install the program

On macOS, Linux or WSL:

Terminal
curl -fsSL https://plannotator.ai/install.sh | bash

On Windows PowerShell:

Code
irm https://plannotator.ai/install.ps1 | iex

Per the docs, the installer adds the plannotator command, checks the download against its SHA-256 checksum, and installs hooks and core skills for the agents it finds. On first run it asks whether to add extra skills; the default answer is no. Check that it worked:

Code
plannotator --version

If piping a script into your shell makes you nervous, the docs offer a binary-only install (--minimal) and a way to pin a version and verify its provenance.

Step 2: Connect your agent

Claude Code needs one extra step. Inside Claude Code, run:

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

Then restart Claude Code. According to the README, Codex and Gemini CLI need nothing more (Gemini needs version 0.36.0 or newer), OpenCode needs "plugin": ["@plannotator/opencode@latest"] in opencode.json, and Pi uses pi install npm:@plannotator/pi-extension. If you are new to hooks and skills, our guide to Claude Code agent skills explains the moving parts.

Step 3: Make your agent write a plan

You do not type a command for this. The README says plan mode is wired in through each agent’s hooks, so the next time your agent finishes a plan, the review screen opens on its own.

Behind the scenes, the README’s flow goes like this:

  1. The agent finishes its plan and asks to exit plan mode (the README calls this step ExitPlanMode).
  2. A hook fires and a local server opens the plan in your browser.
  3. You annotate, then approve or deny.
  4. If you deny, structured feedback goes back to the agent, which revises. A plan diff shows what changed.

Plannotator’s site says you can comment on sections, mark text for deletion, or write replacements, then approve or deny with that feedback attached.

Expected result: a browser tab showing your plan, ready to mark up.

Step 4: Annotate things you already have

Plannotator is not limited to plans. These commands come from the README:

Code
/plannotator-last
/plannotator-annotate README.md
/plannotator-annotate src/
/plannotator-review

The first annotates your agent’s last message. The second and third mark up a file or folder. The last opens a pull-request-style diff viewer for your uncommitted changes, and you can pass a GitHub PR or GitLab merge request URL instead. On Codex, swap the slashes for $plannotator-* skills.

What it does with your data

The README says Plannotator “does not collect usage telemetry or analytics,” and that plans, diffs and annotations stay local by default. It also lists exceptions worth knowing:

  • Each review screen checks GitHub for the latest release when it loads. The README says there is currently no opt-out for that check.
  • “Ask AI” sends the question and relevant context to your configured provider.
  • Sharing a plan sends a link. Per the README, small shares are packed into the link itself, unencrypted, so anyone holding the link can read them. Large shares are encrypted before upload, and hosted pastes expire after 7 days.

Common errors and fixes

  • plannotator: command not found. Open a new terminal. The docs say your PATH may have changed.
  • The review page will not load over SSH or in a container. Over SSH, the README says Plannotator switches to fixed port 19432, and its ~/.ssh/config line is LocalForward 19432 localhost:19432. In a container, or for a different port, set PLANNOTATOR_REMOTE=1 and PLANNOTATOR_PORT=9999, then forward that port instead. New to SSH? See our SSH keys guide.
  • Remote mode is wide open. The README warns that in remote mode the server listens on 0.0.0.0 with no login, so anyone who can reach the port can use it. Keep the port closed to networks you do not trust.
  • No window appears at all. PLANNOTATOR_BROWSER=none opens no browser, and the session URL is always printed.
  • Claude no longer waits for you. On Claude Code 2.1.287 or newer, the README says Claude ends its turn and your decision arrives later as a message. Set PLANNOTATOR_CLAUDE_MOD=0 to restore the classic flow.
  • The plugin will not update. Run claude plugin marketplace update plannotator, then claude plugin update plannotator@plannotator, then restart.
  • You want it gone. Preview with plannotator uninstall --dry-run, then run plannotator uninstall. By default it keeps your plans and history.

The takeaway

A plan you actually read is cheaper than a diff you have to unpick. If you also let your agent drive a browser, see our Chrome DevTools MCP setup.

Sources

Links last checked on 15 November 2026.

Written by Mindloop Editorial

The Mindloop Experience editorial team writes clear, carefully sourced explainers and how-tos on AI and technology, software and the business of tech, for anyone who likes to know how things actually work.

Meet the editorial team

Responses

Write a response

More from Mindloop Experience

See all from Mindloop Experience

You can clap up to 50 times.