backnotprop/plannotator · 13.5k stars · Beginner · 12 min · 2026-11-19

Review your agent's plans and diffs with Plannotator

Plannotator opens a local browser review surface when your coding agent proposes a plan, so you can annotate it, approve or deny it, and send structured feedback straight back.

TL;DR

Plannotator is a local, browser-based review surface for AI coding agents such as Claude Code, Codex, Copilot CLI, Gemini CLI and OpenCode. One installer sets up hooks and slash commands; after that, a plan opens in your browser for markup, and your approval or feedback goes back to the agent. The same UI reviews code diffs and annotates any markdown file.

Why this repo matters

An agent that plans and then runs ahead leaves you with two bad options: read a wall of terminal text, or approve blind. Plannotator puts a review step in between. The README describes it as the place where you "mark it up, comment, and send feedback directly to the agent for it to act on it". It also covers code review (local changes or GitHub and GitLab PRs) and a newer Inbox where several agents leave you questions while they keep working. The repo is Apache 2.0 licensed.

Best practices

  • Use the single installer. The README says one curl installer installs the plannotator binary and auto-detects your agents, configuring hooks, skills and slash commands for each.
  • Let plan review run on its own. For plan mode, the README says no command is needed: when the agent creates a plan, the review surface opens.
  • Deny with annotations, not prose. On deny, the agent receives structured feedback, revises, and the plan diff shows what changed.
  • Review the diff before you commit. /plannotator-review reviews uncommitted changes, and accepts a GitHub PR or GitLab MR URL.
  • Keep sharing deliberate. Small shares live in the link; large ones are encrypted before upload and expire after 7 days. Set PLANNOTATOR_SHARE=disabled to turn sharing off.
  • Mind remote sessions. Over SSH it switches to fixed port 19432; set PLANNOTATOR_REMOTE=1 and PLANNOTATOR_PORT in containers and forward the port.

How-to

Where do I start?

1. Install the binary

Where do I start? Run the installer from the README (macOS, Linux, WSL):

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

On Windows PowerShell it is irm https://plannotator.ai/install.ps1 | iex. Want only the binary? Add --minimal to skip every skill, hook and slash command.

Next: Connect your agent

Try it

Install Plannotator, connect the agent you use, make a small change in a scratch repo, then run /plannotator-review. Leave one line comment, send it, and confirm the agent receives it as feedback.

Pitfalls

  • Skipping the restart. The Copilot CLI and Claude Code plugins need a restart after install.
  • Wrong command syntax on Codex. Slash commands become !plannotator ... or $plannotator-* skills.
  • Remote port not forwarded. Over SSH or in a container the UI is on a fixed port you must forward yourself.
  • Assuming plan interception everywhere. The README says Droid gets commands only, with no plan interception yet.

Next steps