backnotprop/plannotator

Plannotator – AI‑agent‑centric annotation & review tool

What it is

• A local, browser‑based (and terminal‑based) UI that lets you annotate, review and send feedback to a variety of AI coding agents (Claude Code, Codex, Copilot CLI, Gemini CLI, OpenCode, Kiro, Droid, Amp, Pi).
• Works by hooking into the agent’s command/skill system. When the agent produces a plan, HTML artifact, or finished code, Plannotator opens a web page (or a TUI) where you can comment inline and then push the comments back to the agent as its next message.

Key capabilities

Area	What you can do
Plan & document review	Open a markdown plan, spec, or any URL, annotate inline, approve or deny the plan. The agent receives structured feedback and can revise the plan.
Code review	Review local diffs, uncommitted changes, or remote PR/MR from GitHub/GitLab. Supports Git, GitButler, Jujutsu (jj), Perforce (p4). Annotate lines, stage/unstage files, and send “LGTM” or detailed comments back to the agent.
HTML artifact review	Render arbitrary HTML (or raw HTML) and annotate the rendered view.
Terminal UI (Herdr Annotate)	A TUI plugin for the Herdr terminal editor that brings the same annotation experience to the command line. A standalone TUI (plannotator-tui) is also available.
Ask‑AI & AI‑driven reviews	Within the UI you can ask the configured LLM a question about the content you’re reviewing, or launch an AI‑generated review that automatically posts comments to the diff.
Sharing	Export a plan or annotated document via a short‑link (AES‑256‑GCM encrypted payload) or embed small markdown directly in the URL fragment. Legacy link‑sharing UI is still present but being replaced by the hosted Workspaces product.
Integrations	VS Code webview, Obsidian vault auto‑save, Bear notes, and SSH/devcontainer port handling.

Supported agents (out‑of‑the‑box)

• Claude Code, Codex, Copilot CLI, Gemini CLI, OpenCode, Kiro, Droid, Amp, Pi.
• The installer auto‑detects which of these are present and creates the necessary hooks, slash commands, or skills for each.

Installation

# macOS / Linux / WSL – one‑liner installer
curl -fsSL https://plannotator.ai/install.sh | bash

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

• The script downloads the plannotator binary from GitHub Releases, detects installed agents, and writes the required configuration files (hooks, plugins, slash commands, etc.).
• --minimal (or PLANNOTATOR_MINIMAL=1) installs only the binary, leaving you to add the agent‑specific bits manually.
• After the installer finishes, follow the short per‑agent “After the installer” table in the README to copy a plugin file, run a marketplace command, or simply start using the agent (Codex, Gemini, Kiro need no extra step).

Typical workflow

1. Plan mode – No command needed. When your agent emits a plan, Plannotator opens a browser tab automatically.
2. Annotate – Add comments, approve, or deny. The feedback is sent back to the agent session.
3. Code review – Run /plannotator-review (or the equivalent skill) to open a diff viewer, annotate, then send the review back to the agent.
4. HTML review – Use /plannotator-annotate <file.html> --render-html to view and comment on rendered pages.
5. Terminal – Inside Herdr run herdr plugin install plannotator/herdr-annotate and use the same commands in a TUI.

Privacy & network behavior

• All plans, diffs, annotations, and settings stay on your machine by default; no telemetry is collected.
• The only outbound requests are:
  • A one‑time check for the latest Plannotator release on GitHub (can be disabled with --no-git-remote-check or PLANNOTATOR_GIT_REMOTE_CHECK=0).
  • Optional URL fetches (via Jina Reader by default) when you annotate a remote web page.
  • Calls to your configured LLM provider when you use Ask AI or AI‑generated reviews – only the selected question and the relevant context are sent.
  • Sharing services: short‑link uploads encrypt the payload client‑side; the server only stores ciphertext.
• A detailed privacy policy is linked in the README.

Uninstall / purge

plannotator uninstall          # removes binaries, hooks, configs but keeps your local data
plannotator uninstall --purge # deletes all Plannotator‑owned data after a confirmation prompt

Both commands are safe‑guards against accidental data loss (they refuse to delete root/home directories, require explicit purge wording, and provide a dry‑run mode).

Who might benefit?

• Developers who use LLM‑powered coding assistants and want a human‑in‑the‑loop review step before the agent proceeds.
• Teams that need to share annotated plans or code reviews without exposing the full repository (the encrypted short‑link sharing or the upcoming Workspaces product).
• Users who prefer a visual diff/annotation UI but still want the feedback to be consumed automatically by their AI agent.

Bottom line Plannotator bridges the gap between AI‑generated output and human oversight by turning plans, specs, code diffs, and HTML artifacts into an interactive review surface that talks directly to the underlying coding agent. It is a genuine, open‑source software project aimed at improving the safety and productivity of AI‑assisted development.