One Open Source Project a Day (No. 260): Plannotator — An Annotatable Review Desk for AI Coding Agents, for Plans and Code Changes Alike

Introduction

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

This is the 260th article in the "One Open Source Project a Day" series. Today's project is backnotprop's Plannotator.

Working with an AI coding agent has a familiar awkward spot. The agent prints a long plan in the terminal, you want to change step three, and all you can do is type "step three is wrong, change it to..." in the chat. The agent edits the code, you want to comment on a few lines, and again you can only describe them: "that line in the function, the one near the bottom." Information goes back and forth through the conversation, slowly and with losses.

Plannotator gives this step a dedicated review desk. As soon as the agent proposes a plan, a browser interface opens; you mark it up the way you would annotate a document, and one click sends structured feedback back to the agent. It does not make decisions for you; it just makes "keeping a human in the loop" less of a chore.

This article follows the README and the repo's directory listing. I did not install it or run it.

What You Will Learn

• What problem Plannotator solves, and how it differs from giving feedback in chat
• How it opens the review UI automatically through each agent's hooks
• The main features: plan review, annotation, code review, and the inbox
• The privacy model of sharing: what leaves your machine
• How to install it for different agents, and its known limits

Prerequisites

• Having used Claude Code, Codex, or a similar AI coding agent, and knowing what "plan mode" is
• Basic familiarity with hooks and Git diffs
• Optional: some background on Bun and monorepos

Project Background

What It Is

The README's positioning: a local, browser-based review surface for AI coding agents. When an agent proposes a plan or finishes work, a browser UI opens, you annotate, and your feedback goes straight back to the agent. The repo description says it is a workspace to stay in the loop and on top of agents: shape, decide, plan, annotate, review code, share with the team, and send all feedback to agents in one click.

The README lists these supported targets: Claude Code, Codex, Copilot CLI, Gemini CLI, OpenCode, Kiro, Droid, Amp, DeepSeek Harness, and Pi. The apps/ directory also contains plugin folders for Cline, Qwen Code, OpenClaw, Hermes, and others, but they are not in the README's supported list, and I did not verify how mature they are.

Project Stats

• ⭐ GitHub Stars: about 10,237
• 🍴 Forks: about 776
• 💻 Language: TypeScript (a Bun monorepo)
• 📅 Created: 2025-12-28; last pushed 2026-11-13; latest release v0.28.62 (2026-11-12)
• 📄 License: Apache-2.0 or MIT, at your option (dual license)
• 👤 Author: backnotprop, copyright 2025-2026
• 🌐 Website: plannotator.ai

What It Does

The Problem It Solves

With chat-only feedback:
  The agent outputs a long plan → you describe in text what to change
  ↑ location is verbal, annotations are not structured, and changes are hard to compare
 
With Plannotator:
  The agent proposes a plan → a browser review UI opens → annotate paragraph by paragraph → approve or send back
  ↓ structured feedback returns to the same agent session
  ↑ after the agent revises, the UI shows a diff of the plan

Main Capabilities

Common commands:

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

Codex works a little differently: use !plannotator … or $plannotator-* skills.

Quick Install

The universal installer detects which agents you have:

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

For the binary only, add --minimal (or set PLANNOTATOR_MINIMAL=1); to pin a version use --version vX.Y.Z.

After that, add one step per agent:

Steps for Kiro, Amp, and T3 Code are in the README. To update, rerun the installer; to uninstall, use plannotator uninstall, where --purge removes all data and --dry-run previews first.

A Deeper Look

How the Plan Review "Pops Up"

The core is hooks. For Claude Code, the README describes this flow:

1. In plan mode, the agent finishes a plan and calls ExitPlanMode
2. That fires the PermissionRequest hook
3. A local server reads the plan, and the browser opens the review UI
4. You approve and the agent proceeds; you deny and structured feedback goes back to the agent

When configuring the hook by hand, the matcher is ExitPlanMode and the timeout is 345600 seconds (4 days), so you can step away and come back to review. The README also notes that on Claude Code 2.1.287 and later, the agent ends its turn first and your decision arrives afterward as a message; to go back to the classic flow, set PLANNOTATOR_CLAUDE_MOD=0.

Code review is similar: /plannotator-review captures the git diff (or fetches the PR), opens a diff viewer, you comment line by line, and the feedback returns to the agent session. Approving sends "LGTM."

What is clever here is that it does not invent a new workflow. It hangs on checkpoints the agent already has (leaving plan mode, finishing a change) and just swaps "read and reply in chat" for "read and annotate in a dedicated UI."

Sharing and Privacy: What Leaves Your Machine

The README is detailed here, and it is worth reading on its own:

• No telemetry or analytics by default; plans, diffs, and annotations stay local
• Each UI checks GitHub for the latest release when it loads, and there is no way to turn this off
• Git review may run git ls-remote against origin; disable it with --no-git-remote-check, PLANNOTATOR_GIT_REMOTE_CHECK=0, or the config { "gitRemoteCheck": false }
• Content only leaves your machine for network features: URL fetching (Jina Reader by default), GitHub/GitLab data, AI providers, and sharing
• Small shares: compressed into the URL fragment (the part after #). The fragment is not sent to the sharing portal, but it is not encrypted
• Large Markdown and raw HTML shares: encrypted with AES-256-GCM before upload; the server stores only ciphertext and the key stays in the URL fragment; content expires after 7 days. The README says the model is similar to PrivateBin
• PLANNOTATOR_SHARE=disabled turns sharing off completely
• The sharing service can be self-hosted: PLANNOTATOR_SHARE_URL points to a custom portal and PLANNOTATOR_PASTE_URL to a custom storage API

The README also warns that anyone who holds the full share link can read the content, and that link sharing is moving to "deprecated but still supported," with Hosted Workspaces as the team direction; no removal date is given.

Remote and SSH

On a remote machine, SSH is detected automatically and port 19432 is used. You need to add a forward in your local ~/.ssh/config:

LocalForward 19432 localhost:19432

The README is blunt about the security risk: in remote mode the server listens on 0.0.0.0 with no login, so do not expose this port to untrusted networks.

Configuration

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

Supply Chain and Releases

Release binaries come with SHA256 sidecar files, SLSA provenance is available from v0.17.2, and a CycloneDX software bill of materials is attested through Sigstore (note it is a release-wide inventory, not one per binary). To verify at install time, add --verify-attestation (needs gh) or set { "verifyAttestation": true }.

Repo Layout

It is a Bun monorepo:

• apps/: the integration layer and services for each agent, including hook, review, inbox, opencode-plugin, pi-extension, paste-service, portal, vscode-extension, and more
• packages/: shared code, including ui, editor, review-editor, server, core, ai, and t3-code

Development commands are bun install, bun run dev:hook, and bun run build; mind the build order: build apps/review before the hook.

Limits and Cautions

The README lists these limits itself:

1. Codex hooks are still experimental, and native Windows needs manual setup
2. Droid cannot intercept plans yet
3. The GitHub release check cannot be disabled
4. Remote mode has no authentication
5. Share links are readable by anyone with the full link

Two more points are my own judgment:

• Many agents are covered, but not equally deeply: some get full plan interception, others only commands; check the row for your own agent in the README before relying on it
• I did not verify the "no telemetry" claim: the README states it, but apps/ contains a directory named telemetry. I did not read its contents, so I cannot say how the two relate. If privacy matters to you, look at it yourself

Project Links and Resources

• 🌟 GitHub: https://github.com/backnotprop/plannotator
• 🌐 Website: https://plannotator.ai
• 📄 License: Apache-2.0 or MIT
• 🔒 Security policy: SECURITY.md at the repo root
• 🤝 Contributing: CONTRIBUTING.md at the repo root

Summary

Key Takeaways

1. It solves feedback efficiency: swap "describing in chat" for "annotating in a UI," so feedback is structured and precisely located
2. It hangs on checkpoints the agent already has: hooks open it when leaving plan mode or finishing a change, with no change to your workflow
3. Broad coverage: ten agents, with annotation, code review, and an inbox beyond plan review
4. A clear privacy model: local by default; sharing has two tiers (URL fragment and encrypted upload), and can be self-hosted or turned off
5. Explicit limits: experimental Codex hooks, no auth in remote mode, and a version check that cannot be disabled

Who This Is For

• Developers who have agents plan before acting and want to annotate plans precisely
• People who review agent changes and PRs, especially those who want to return all comments to the agent at once
• Teams that want a consistent way of giving feedback to agents

Suggested First Steps

Install it on an agent you know well (Claude Code has the most complete steps), deliberately ask for a plan with an obvious flaw, and try annotating and sending it back; then see whether the agent's revision matches your feedback. If you use it on a remote server, read the "Remote and SSH" section before opening the port. To see how it plugs into different agents, compare the apps/hook and apps/opencode-plugin directories.

Check out PrimeSkills — a curated marketplace of AI agents and skills that have been validated in real-world, enterprise-grade workflows. No fluff, just what actually works.

Find more useful knowledge and interesting products on my Homepage