跪拜 Guibai
← Back to the summary

Plannotator Brings Browser-Based Annotation to AI Coding Agents' Plans and Diffs

One Open Source Project a Day (Part 260): Plannotator — A 'Annotatable Review Desk' for AI Coding Agents, With Plan and Code Changes You Can Mark Up Line by Line in the Browser

Author: 冬奇Lab

Introduction

"Stay in the loop and on top of agents."

This is Part 260 of the "One Open Source Project a Day" series. Today's project is Plannotator by backnotprop.

Working with AI coding agents has a common awkwardness: the agent spits out a long plan in the terminal, you want to change step three, but you can only type in the chat box, "Step three is wrong, change it to…"; after the agent finishes code changes, you want to comment on a few lines, but you can only describe it verbally, "that line in that function." Information shuttles back and forth through conversation, which is slow and easy to lose.

Plannotator's approach is to give this stage a dedicated review desk: as soon as the agent proposes a plan, a browser interface pops up, where you can annotate section by section like marking up a document, and with one click send structured feedback back to the agent. It doesn't make decisions for you; it just makes "human in the loop" smoother.

This article is based on the README and repository directory. I did not install it or run it myself.

What you will learn

Prerequisites


Project Background

Project Overview

The README positions it as: a local, browser-based review interface for AI coding agents. After an agent proposes a plan or finishes work, the browser interface pops up, you make annotations, and send feedback directly back to the agent. The repository description's original words: it's a workbench to "stay in the loop and stay on top of agents": shape, decide, plan, annotate, review code, share with the team, and send all feedback to the agent in one click.

The README lists supported agents: Claude Code, Codex, Copilot CLI, Gemini CLI, OpenCode, Kiro, Droid, Amp, DeepSeek Harness, and Pi. Under the repository's apps/ directory, you can also see plugin directories for Cline, Qwen Code, OpenClaw, Hermes, etc., but they are not in the README's support list, and I haven't verified their maturity.

Project Data


Main Features

The Problem It Solves

Using only chat feedback:
  Agent outputs a long plan → you describe in the chat box what to change
  ↑ Location relies on oral description, annotations are not structured, and after changes it's hard to compare

With Plannotator:
  Agent proposes a plan → browser opens a review interface → annotate section by section → approve or reject
  ↓ Structured feedback goes back to the same agent session
  ↑ After the agent modifies, the interface also shows the diff of the plan before and after

Main Capabilities

Feature Description
Plan review Automatically opens via each agent's hooks; you can approve, or reject with structured feedback; after the agent makes changes, it shows the plan diff
Annotations Supports Markdown files, folders, URLs, and HTML; /plannotator-last can annotate the agent's last message
Code review Local changes, and GitHub/GitLab PR/MR; supports Git, GitButler, Jujutsu, Perforce; can comment on diffs, suggest code, stage files, and review static patches via --patch-file
Built-in AI Can ask AI questions, and a review agent can post comments directly on the diff
Inbox plannotator inbox: while the agent continues working, it leaves questions, files, and review requests here
Terminal review Herdr Annotate / Plannotator TUI, installable via brew install plannotator/tap/plannotator-tui
Vim keybindings Off by default, supports j/k navigation, v/V selection
Integrations VS Code, Obsidian, Bear, Notion (requires NOTION_TOKEN), GitHub/GitLab

Common commands:

/plannotator-annotate README.md       Annotate a file
/plannotator-review                  Review local changes
/plannotator-review <github-pr-url>   Review a specific PR
/plannotator-last                    Annotate the agent's last message
plannotator sessions                View sessions
plannotator archive                 Archive

In Codex, usage is slightly different: use skills like !plannotator … or $plannotator-*.

Quick Install

The universal installer automatically detects which agents you have installed:

# macOS / Linux / WSL
curl -fsSL https://plannotator.ai/install.sh | bash

# Windows
irm https://plannotator.ai/install.ps1 | iex

Add --minimal (or set PLANNOTATOR_MINIMAL=1) to install only the binary; pin a version with --version vX.Y.Z.

After installation, add one step per agent:

Agent Additional Step
Claude Code /plugin marketplace add backnotprop/plannotator, then /plugin install plannotator@plannotator, then restart
Codex No extra step; plan review uses the experimental Stop Hook
Copilot CLI /plugin marketplace add backnotprop/plannotator, then /plugin install plannotator-copilot@plannotator; works in plan mode (Shift+Tab)
Gemini CLI No extra step; requires version 0.36.0 or higher
OpenCode Add "plugin": ["@plannotator/opencode@latest"] to opencode.json
Pi pi install npm:@plannotator/pi-extension, launch with --plan
DeepSeek Harness dsh plugin --profile <profile> add @plannotator/dsh
Droid droid plugin marketplace add https://github.com/backnotprop/plannotator, then droid plugin install plannotator@plannotator; currently only commands, no plan interception

Kiro, Amp, and T3 Code steps are described separately in the README. Updating is just re-running the installer; uninstall with plannotator uninstall, add --purge to clear all data, --dry-run to preview.


Detailed Project Analysis

How Plan Review "Pops Up"

The core is hooks. Using Claude Code as an example, the README describes the flow:

  1. The agent prepares a plan in plan mode and calls ExitPlanMode
  2. This triggers the PermissionRequest Hook
  3. The local service reads the plan content, and the browser opens the review interface
  4. If you approve, the agent continues; if you reject, structured feedback goes back to the agent

When configuring the hook manually, the matcher is ExitPlanMode, with a timeout of 345600 seconds (4 days), meaning you can leave for a long time and come back to review. The README also mentions that in Claude Code 2.1.287 and above, the agent ends its current turn first, and your decision arrives as a message later; to return to the classic flow, set PLANNOTATOR_CLAUDE_MOD=0.

Code review works similarly: /plannotator-review grabs the git diff (or pulls a PR), opens a diff viewer, you comment line by line, and feedback goes back to the agent session. On approval, it sends "LGTM."

The clever part of this design is that it doesn't create a separate "new workflow"; it attaches to checkpoints the agent already has (exiting plan mode, finishing changes), and simply replaces "reading and replying in chat" with "reading and annotating in a dedicated interface."

Sharing and Privacy: What Leaves Your Machine

The README is very detailed here, worth a separate look:

The README also warns: anyone holding the full share link can read the content; and link sharing is transitioning to "deprecated but still supported," with the team's direction being Hosted Workspaces, with no removal date given.

Remote and SSH

To use on a remote machine, SSH is automatically detected and uses port 19432. You need to add a forwarding line to your local ~/.ssh/config:

LocalForward 19432 localhost:19432

The README is blunt about the security risk here: in remote mode, the service listens on 0.0.0.0 with no login authentication, so don't expose this port to untrusted networks.

Configuration

Settings can be placed in cookies, environment variables, or ~/.plannotator/config.json. Common environment variables:

Variable Purpose
PLANNOTATOR_PORT Port; random for local by default, 19432 for remote
PLANNOTATOR_BROWSER Set to none to not auto-open the browser
PLANNOTATOR_AI Set to disabled to turn off built-in AI
PLANNOTATOR_DATA_DIR Data directory, default ~/.plannotator
PLANNOTATOR_SHARE Set to disabled to turn off sharing

Supply Chain and Release

Released binaries come with SHA256 checksums. Starting with v0.17.2, SLSA provenance is provided, and a CycloneDX software bill of materials is attested via Sigstore (note: it's for the entire release, not per binary). To verify during installation, add --verify-attestation (requires gh), or set { "verifyAttestation": true } in config.

Repository Structure

This is a Bun Monorepo:

Development commands are bun install, bun run dev:hook, bun run build. Note the build order: build apps/review first, then the hook.

Limitations and Considerations

The README lists its own limitations:

  1. Codex's hooks are still experimental, and native Windows requires manual configuration
  2. Droid cannot intercept plans yet
  3. The GitHub version check cannot be disabled
  4. Remote mode has no authentication
  5. Share links are readable by anyone holding the full link

I add two judgments:


Project Address and Resources


Summary and Outlook

Key Points Recap

  1. Solves the "feedback efficiency" problem: replaces "oral description in chat" with "annotation in an interface," making feedback structured and location precise
  2. Attaches to checkpoints the agent already has: uses hooks to trigger on exit from plan mode and on change completion, without altering your workflow
  3. Broad coverage: ten agents, and beyond plan review it includes annotation, code review, and Inbox
  4. Clear privacy model: local by default; sharing comes in "URL fragment" and "encrypted upload" tiers, and can be self-hosted or disabled
  5. Explicit limitations: Codex hooks are experimental, remote mode has no auth, and version checking cannot be disabled

Who It's For

Learning Suggestions

Start by installing it on a familiar agent (Claude Code has the most complete steps), deliberately make it produce a plan with an obvious problem, try annotating and rejecting once, and see whether the agent's modifications after receiving feedback match your intentions. If you use it on a remote server, read the "Remote and SSH" section before opening any ports. To understand how it integrates with different agents, compare the apps/hook and apps/opencode-plugin directories.


Welcome to PrimeSkills — a curated marketplace of AI agents and skills, all validated through real enterprise-grade workflows. No hype, only what actually works.

For more practical knowledge and interesting products, visit my personal homepage

Comments

Top 1 from juejin.cn, machine-translated. The original thread is authoritative.

shushenghong

Structured annotations are far more convenient than describing "that line" in the chat box. Another point that's easy to miss: annotations only apply to this session. When the same type of feedback gets annotated a second time, we turn it into a rule and put it in a file in the repo for the agent to read, so every agent in the team will read it first, without each person having to annotate it again.