plannotator
<p align="center"> <img src="apps/marketing/public/og-image.webp" alt="Plannotator" width="80%" /> </p> # Plannotator Review AI-agent plans and code diffs in a browser. Add inline annotations, send structured feedback back to your agent, and share encrypted review links with teammates. Works with **Claude Code**, **Copilot CLI**, **Gemini CLI**, **OpenCode**, **Pi**, **Codex**, **Droid**, and **Amp**. **Plan Mode Demos:** <table> <tr> <td align="center" width="50%"> <h3>Claude Code</h3> <a href="https://www.youtube.com/watch?v=a_AT7cEN_9I"> <img src="apps/marketing/public/youtube.png" alt="Claude Code Demo" width="100%" /> </a> <p><a href="https://www.youtube.com/watch?v=a_AT7cEN_9I">Watch Demo</a></p> </td> <td align="center" width="50%"> <h3>OpenCode</h3> <a href="https://youtu.be/_N7uo0EFI-U"> <img src="apps/marketing/public/youtube-opencode.png" alt="OpenCode Demo" width="100%" /> </a> <p><a href="https://youtu.be/_N7uo0EFI-U">Watch Demo</a></p> </td> </tr> </table> **Annotate:** Plans, specs, folders, files, urls. send feedback directly to agents. **New:** [Code Review](https://x.com/backnotprop/status/2031145299738263567?s=20) - send your feedback to agents - built-in: - ask ai - agent code reviews ### Features <table> <tr><td><strong>Visual Plan Review</strong></td><td>Built-in hook</td><td>Approve or deny agent plans with inline annotations and Ask AI side chat</td></tr> <tr><td><strong>Plan Diff</strong></td><td>Automatic</td><td>See what changed when the agent revises a plan</td></tr> <tr><td><strong>Code Review</strong></td><td><code>/plannotator-review</code></td><td>View git diffs or remote PRs. Package annotations and ask AI about the code as you review.</td></tr> <tr><td><strong>Annotate Any File</strong></td><td><code>/plannotator-annotate <file|folder|url></code></td><td>Annotate markdown, HTML, URLs, or folders, ask AI about the active document, and send feedback to your agent</td></tr> <tr><td><strong>Annotate Last Message</strong></td><td><code>/plannotator-last</code></td><td>Annotate the agent's last response and send structured feedback</td></tr> </table> #### Sharing Plans Plannotator lets you privately share plans, annotations, and feedback with colleagues. For example, a colleague can annotate a shared plan, and you can import their feedback to send directly back to the coding agent. **Small plans** are encoded entirely in the URL hash. No server involved, nothing stored anywhere. **Large plans** use a short link service with **end-to-end encryption**. Your plan is encrypted with AES-256-GCM in your browser before upload. The server stores only ciphertext it cannot read. The decryption key lives only in the URL you share. Pastes auto-delete after 7 days. - Zero-knowledge storage, similar to [PrivateBin](https://privatebin.info/) - Fully open source and **self-hostable** ([see docs](https://plannotator.ai/docs/guides/sharing-and-collaboration/)) ## Install - [Claude Code](#install-for-claude-code) - [Copilot CLI](#install-for-copilot-cli) - [Gemini CLI](#install-for-gemini-cli) - [OpenCode](#install-for-opencode) - [Pi](#install-for-pi) - [Codex](#install-for-codex) - [Droid](#install-for-droid) ## Install for Claude Code **Install the `plannotator` command:** **macOS / Linux / WSL:** ```bash curl -fsSL https://plannotator.ai/install.sh | bash ``` **Windows PowerShell:** ```powershell irm https://plannotator.ai/install.ps1 | iex ``` **Then in Claude Code:** ``` /plugin marketplace add backnotprop/plannotator ``` Restart Claude Code after plugin install. <details> <summary>Pin a specific version or verify provenance</summary> ```bash curl -fsSL https://plannotator.ai/install.sh | bash -s -- --version vX.Y.Z ``` ```powershell & ([scriptblock]::Create((irm https://plannotator.ai/install.ps1))) -Version vX.Y.Z ``` Every released binary ships with a SHA256 sidecar (verified automatically). [SLSA provenance](https://slsa.dev/) verification is supported from v0.17.2 onwards — see the [installation docs](https://plannotator.ai/docs/getting-started/installation/#verifying-your-install) for details. </details> See [apps/hook/README.md](apps/hook/README.md) for detailed installation instructions including a `manual hook` approach. --- ## Install for Copilot CLI **Install the `plannotator` command:** **macOS / Linux / WSL:** ```bash curl -fsSL https://plannotator.ai/install.sh | bash ``` **Windows PowerShell:** ```powershell irm https://plannotator.ai/install.ps1 | iex ``` **Then in Copilot CLI:** ``` /plugin marketplace add backnotprop/plannotator /plugin install plannotator-copilot@plannotator ``` Restart Copilot CLI after plugin install. Plan review activates automatically when you use plan mode (`Shift+Tab` to enter plan mode). See [apps/copilot/README.md](apps/copilot/README.md) for details. --- ## Install for Gemini CLI **Install the `plannotator` command:** **macOS / Linux / WSL:** ```bash curl -fsSL https://plannotator.ai/install.sh | bash ``` **Windows PowerShell:** ```powershell irm https://plannotator.ai/install.ps1 | iex ``` The installer auto-detects Gemini CLI (checks for `~/.gemini`) and configures the plan review hook and policy. It also installs `/plannotator-review` and `/plannotator-annotate` slash commands. **Then in Gemini CLI:** ``` /plan # Enter plan mode — plans open in your browser /plannotator-review # Code review for current changes /plannotator-review <pr-url> # Review a GitHub pull request /plannotator-annotate <file.md> # Annotate a markdown file ``` Requires Gemini CLI 0.36.0 or later. See [apps/gemini/README.md](apps/gemini/README.md) for details. --- ## Install for OpenCode Add to your `opencode.json`: ```json { "plugin": ["@plannotator/opencode@latest"] } ``` **Run the install script** to get `/plannotator-review`: ```bash curl -fsSL https://plannotator.ai/install.sh | bash ``` **Windows:** ```powershell irm https://plannotator.ai/install.ps1 | iex ``` This also clears any cached plugin versions. Then restart OpenCode. --- ## Install for Pi ```bash pi install npm:@plannotator/pi-extension ``` Then start Pi with `--plan` to enter plan mode, or toggle it during a session with `/plannotator`. See [apps/pi-extension/README.md](apps/pi-extension/README.md) for full usage details, commands, and flags. --- ## Install for Codex **Install the `plannotator` command:** **macOS / Linux / WSL:** ```bash curl -fsSL https://plannotator.ai/install.sh | bash ``` The installer also enables Codex Stop hooks when Codex is installed or `~/.codex` already exists. Restart Codex Desktop after installing or changing hooks. **Windows PowerShell:** ```powershell irm https://plannotator.ai/install.ps1 | iex ``` Codex plan review is automatic on macOS, Linux, and WSL. Codex hooks are currently disabled on Windows in the official Codex docs, so the Windows installer does not enable them automatically; the direct `!plannotator` commands still work. **Then in Codex — feedback flows back into the agent loop automatically:** ``` $plannotator-review # Code review skill for current changes $plannotator-annotate # Annotate a markdown file, URL, or folder $plannotator-last # Annotate the last agent message ``` ``` !plannotator review # Code review for current changes !plannotator review <pr-url> # Review a GitHub pull request !plannotator annotate file.md # Annotate a markdown file !plannotator last # Annotate the last agent message ``` Plan review uses Codex's experimental `Stop` hook on macOS, Linux, and WSL. See [apps/codex/README.md](apps/codex/README.md) for details. --- ## Install for Droid **Install the `plannotator` command:** **macOS / Linux / WSL:** ```bash curl -fsSL https://plannotator.ai/install.sh | bash ``` **Windows PowerShell:** ```powershell irm https://plannotator.ai/install.ps1 | iex ``` **Then in Droid:** ```bash droid plugin marketplace add https://github.com/backnotprop/plannotator droid plugin install plannotator@plannotator ``` This Droid plugin is commands-only. It adds: ```text /plannotator-review /plannotator-annotate <file|folder|url> /plannotator-last ``` It does not currently intercept Droid's planning flow. See [apps/droid-plugin/README.md](apps/droid-plugin/README.md) for details. --- ## How It Works When your AI agent finishes planning, Plannotator: 1. Opens the Plannotator UI in your browser 2. Lets you annotate the plan visually (delete, insert, replace, comment) 3. Lets you ask AI about the plan or a highlighted selection when a provider is available 4. **Approve** → Agent proceeds with implementation 5. **Request changes** → Your annotations are sent back as structured feedback (Similar flow for code review, except you can also comment on specific lines of code diffs) --- ## License Copyright 2025-2026 backnotprop This project is licensed under either of - [Apache License, Version 2.0](LICENSE-APACHE) ([http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)) - [MIT license](LICENSE-MIT) ([http://opensource.org/licenses/MIT](http://opensource.org/licenses/MIT)) at your option. ### Contribution Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. ## Development To make the global `plannotator` command run from this checkout: ```bash bun install bun link ``` After linking, commands like `plannotator review` use `apps/hook/server/index.ts` from your local repo. Rebuild the bundled HTML when changing UI code: ```bash bun run --cwd apps/review build && bun run build:hook ```