https://github.com/backnotprop/plannotator
Annotate and review coding agent plans and code diffs visually, share with your team, send feedback to agents with one click.
https://github.com/backnotprop/plannotator
agents claude-code code-review codex obsidian opencode pi-mono plan-mode skills
Last synced: 1 day ago
JSON representation
Annotate and review coding agent plans and code diffs visually, share with your team, send feedback to agents with one click.
- Host: GitHub
- URL: https://github.com/backnotprop/plannotator
- Owner: backnotprop
- License: apache-2.0
- Created: 2025-12-28T02:09:40.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-05-09T01:15:13.000Z (4 days ago)
- Last Synced: 2026-05-09T01:30:01.067Z (4 days ago)
- Topics: agents, claude-code, code-review, codex, obsidian, opencode, pi-mono, plan-mode, skills
- Language: TypeScript
- Homepage: https://plannotator.ai
- Size: 65.7 MB
- Stars: 5,080
- Watchers: 15
- Forks: 351
- Open Issues: 95
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE-APACHE
- Agents: AGENTS.md
Awesome Lists containing this project
- awesome-claude-code - backnotprop/plannotator - square&logo=github) | Visual plan review and annotation tool for Claude Code and OpenCode | (GUI & IDE)
- awesome-claude-skills - plannotator - Interactive plan review UI for Claude Code with visual annotation, offline sharing, and Obsidian/Bear integration. (🤝 Collaboration & Project Management)
README
# Plannotator
Interactive Plan & Code Review for AI Coding Agents. Mark up and refine your plans or code diffs using a visual UI, share for team collaboration, and seamlessly integrate with **Claude Code**, **Copilot CLI**, **Gemini CLI**, **OpenCode**, **Pi**, and **Codex**.
**Plan Mode Demos:**
Claude Code
OpenCode
**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
Visual Plan ReviewBuilt-in hookApprove or deny agent plans with inline annotations
Plan DiffAutomaticSee what changed when the agent revises a plan
Code Review/plannotator-reviewView git diffs or remote PRs. Package annotations and ask AI about the code as you review.
Annotate Any File/plannotator-annotate <file|folder|url>Annotate markdown, HTML, URLs, or folders and send feedback to your agent
Annotate Last Message/plannotator-lastAnnotate the agent's last response and send structured feedback
#### 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)
## 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.
Pin a specific version or verify provenance
```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.
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 # Review a GitHub pull request
/plannotator-annotate # 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 # 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.
---
## 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. **Approve** → Agent proceeds with implementation
4. **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
```