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
- What problem Plannotator solves, and how it differs from giving feedback directly in the chat box
- How it automatically pops up the review interface via each agent's hooks
- The main features: plan review, annotations, code review, and Inbox
- The privacy model of the sharing feature: what leaves your machine
- How to install it to different agents, and known limitations
Prerequisites
- Have used Claude Code, Codex, or a similar AI coding agent, and know about "plan mode"
- Basic understanding of hooks and Git diff
- Optional: familiarity with Bun and Monorepos
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
- ⭐ GitHub Stars: ~10,237
- 🍴 Forks: ~776
- 💻 Language: TypeScript (Bun Monorepo)
- 📅 Created: 2025-12-28; last push on 2026-11-13; latest release v0.28.62 (2026-11-12)
- 📄 License: Apache-2.0 or MIT (dual license)
- 👤 Author: backnotprop, copyright 2025-2026
- 🌐 Website: plannotator.ai
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:
- The agent prepares a plan in plan mode and calls
ExitPlanMode - This triggers the
PermissionRequestHook - The local service reads the plan content, and the browser opens the review interface
- 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:
- No telemetry or analytics by default; plans, diffs, and annotations stay local
- Each interface load checks GitHub for the latest version; this has no opt-out
- Git review may run
git ls-remoteagainstorigin; you can disable it with--no-git-remote-check,PLANNOTATOR_GIT_REMOTE_CHECK=0, or{ "gitRemoteCheck": false }in config - Only network-related features cause content to leave your machine: fetching URLs (defaults to Jina Reader), GitHub/GitLab data, AI providers, and sharing
- Small-share: compressed into the URL fragment (the part after
#). The fragment is not sent to the share portal, but it is not encrypted - Large Markdown and raw HTML shares: encrypted with AES-256-GCM before upload; the server only stores ciphertext, the key stays in the URL fragment, and content expires after 7 days. The README says its model is similar to PrivateBin
- Set
PLANNOTATOR_SHARE=disabledto completely disable sharing - The share service can be self-hosted:
PLANNOTATOR_SHARE_URLpoints to a custom portal,PLANNOTATOR_PASTE_URLto a custom storage API
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:
apps/: integration layers and services for each agent, includinghook,review,inbox,opencode-plugin,pi-extension,paste-service,portal,vscode-extension, etc.packages/: shared code, includingui,editor,review-editor,server,core,ai,t3-code, etc.
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:
- Codex's hooks are still experimental, and native Windows requires manual configuration
- Droid cannot intercept plans yet
- The GitHub version check cannot be disabled
- Remote mode has no authentication
- Share links are readable by anyone holding the full link
I add two judgments:
- Coverage is wide but depth varies: some agents have full plan interception, others only commands; check the README's row for your specific agent before using
- "No telemetry" I have not verified: the README claims it, but there's a directory named
telemetryunderapps/. I haven't read its contents, so I can't assert the relationship. If you're privacy-sensitive, I suggest you look yourself
Project Address and Resources
- 🌟 GitHub: https://github.com/backnotprop/plannotator
- 🌐 Website: https://plannotator.ai
- 📄 License: Apache-2.0 or MIT
- 🔒 Security Policy:
SECURITY.mdin the repository root - 🤝 Contributing Guide:
CONTRIBUTING.mdin the repository root
Summary and Outlook
Key Points Recap
- Solves the "feedback efficiency" problem: replaces "oral description in chat" with "annotation in an interface," making feedback structured and location precise
- Attaches to checkpoints the agent already has: uses hooks to trigger on exit from plan mode and on change completion, without altering your workflow
- Broad coverage: ten agents, and beyond plan review it includes annotation, code review, and Inbox
- Clear privacy model: local by default; sharing comes in "URL fragment" and "encrypted upload" tiers, and can be self-hosted or disabled
- Explicit limitations: Codex hooks are experimental, remote mode has no auth, and version checking cannot be disabled
Who It's For
- Developers who frequently have an agent propose a plan before acting, and want to annotate precisely
- People who need to review agent changes and PRs, especially those who want to send comments back to the agent in one go
- Teams that want to standardize "how to give feedback to an agent"
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
Top 1 from juejin.cn, machine-translated. The original thread is authoritative.
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.