backnotprop/plannotator

Plannotator – A local, browser‑based review UI for AI coding agents

What it is – Plannotator is a desktop‑only (no cloud‑service required) tool that opens a web UI (or a terminal UI via Herdr Annotate) whenever an AI‑powered coding assistant (Claude Code, Codex, Copilot CLI, Gemini CLI, OpenCode, Kiro, Droid, Amp, Pi, etc.) produces a plan, a piece of HTML, or finished code. You can annotate the content, comment on diffs, and send the feedback back to the agent so it can revise its output.

Core capabilities

• Plan / document review – annotate markdown plans, specs, or any URL‑fetched page. The UI shows inline comments and a “send feedback” button.
• Code review – works on local changes or remote PR/MR URLs (GitHub, GitLab, GitButler, Perforce). Shows a file‑tree and side‑by‑side diff where you can comment, stage/unstage, and reply “LGTM”.
• HTML artifact review – renders raw HTML and lets you mark it up before sending feedback.
• AI‑in‑the‑loop – you can ask the connected LLM a question about the material you’re reviewing, or launch an AI‑generated review that posts comments automatically.
• Terminal mode – the Herdr Annotate plugin brings the same UI into the terminal (via the Herdr TUI). A standalone TUI is also available as plannotator-tui.

How it works

1. The agent fires a hook (e.g., ExitPlanMode).
2. Plannotator’s local server receives the plan or diff.
3. Your default browser opens the review UI.
4. After you annotate, the tool sends a structured response back through the same hook, letting the agent continue or revise.

Installation

• One‑line installer for macOS, Linux, WSL, and Windows PowerShell that downloads the plannotator binary, detects installed agents, and writes the necessary hooks/skills/commands.
• --minimal flag installs only the binary, leaving out all agent‑specific integrations.
• After the installer, follow the short per‑agent steps (copy a plugin file for Amp, add a marketplace entry for Claude Code, etc.) – the README lists each agent with a link to its detailed setup.

Usage shortcuts

/plannotator-annotate README.md                # annotate a local file
/plannotator-annotate https://example.com     # fetch & annotate a URL
/plannotator-review                           # review current git diff
/plannotator-review https://github.com/...    # review a PR/MR
/plannotator-last                             # annotate the agent’s last reply
plannotator sessions                          # list/open saved sessions

(For Codex the commands are prefixed with ! or $.)

Integrations

• VS Code webview, Obsidian vault auto‑save, Bear notes, GitHub/GitLab PR fetching, GitButler workspaces, Perforce, remote SSH/devcontainer port forwarding.
• All integrations are optional; the core UI works without any of them.

Privacy & networking

• No telemetry; all plans, diffs, annotations, and settings stay on the local machine unless you explicitly share them.
• Network calls only happen when you request external resources: fetching a URL (via Jina Reader by default), pulling PR data from GitHub/GitLab, sending a question to your configured LLM provider, or using the optional link‑sharing service (which encrypts large payloads client‑side with AES‑256‑GCM).
• The installer checks GitHub for the latest release but does not transmit any of your content.

Sharing

• Small markdown snippets are encoded in the URL fragment (visible to anyone with the link).
• Larger payloads use a short‑link service that stores only ciphertext; the decryption key lives in the fragment.
• A hosted “Workspaces” product is mentioned for team collaboration, but the open‑source app remains purely local.

Security

• Every binary release ships with a SHA‑256 checksum and SLSA provenance.
• A CycloneDX SBOM and Grype scan are attached to each release; the README points to verification commands.

Uninstall / purge

• plannotator uninstall removes binaries and config but keeps your local data.
• plannotator uninstall --purge erases all Plannotator data after a confirmation prompt.

Bottom line – Plannotator is a focused, locally‑hosted UI that lets developers keep a human‑in‑the‑loop when using AI coding assistants, providing plan review, code diff annotation, and HTML artifact feedback without sending proprietary code to any third‑party service.