Michael Ramos
dd04e6b1cd
* feat: add Conventional Comments support to code review Add structured label system based on the Conventional Comments spec (conventionalcomments.org) to the code review annotation toolbar. - Label picker with 9 default labels (suggestion, nit, question, issue, praise, thought, note, todo, chore) shown above the comment textarea - Per-label blocking/non-blocking toggle for labels where severity is ambiguous (issue, suggestion, todo, chore) - Labels exported as `**label** (decoration): text` in markdown feedback, naturally readable on GitHub and machine-parseable - Label badges shown on inline annotations and sidebar cards - Settings tab (Comments) with: master on/off toggle, editable label list with add/remove/rename, per-label blocking decorator toggle, educational intro with spec link and example output - Feature is off by default, persisted via config store - Custom labels supported via settings (up to 12) For provenance purposes, this commit was AI assisted. * fix(review): address conventional comments review feedback Fix label clearing bug where editing an annotation to remove its conventional label silently preserved the old value. Fix parseCCLabels accepting 'non-blocking' as a truthy blocking value. Fix duplicate custom label identities when adding multiple labels. Prepend conventional prefix to platform PR/MR inline comments. For provenance purposes, this commit was AI assisted. * fix(server): persist conventionalComments setting to config.json All six server config handlers (bun plan/review/annotate + pi plan/review/annotate) now accept and save the conventionalComments boolean, so the setting survives server restarts. For provenance purposes, this commit was AI assisted. * fix: add conventionalComments to server config round-trip getServerConfig() was not returning the conventionalComments value from config.json, so the setting silently reset to false on cookie clear or new browser sessions. Also adds the field to the PlannotatorConfig interface so saveConfig() is properly typed. For provenance purposes, this commit was AI assisted. * fix: label display, export, and draft persistence for conventional comments - Remove slug derivation from label editing — store display text verbatim so badges and exports show what the user typed - Emit conventional prefix in export even when annotation has no prose text (suggestion-only annotations were losing their label) - Include conventionalLabel in draft save condition so label selection persists across file switches For provenance purposes, this commit was AI assisted. * fix: spec-compliant export format and empty label support - Wrap label + decorations + colon in markdown bold per the Conventional Comments spec examples (was bolding only the label) - Allow users to clear all labels — empty array no longer falls back to defaults in either the picker or the settings parser - Enable blocking decorator on the question label by default; the spec permits blocking questions and they sometimes are critical For provenance purposes, this commit was AI assisted. * fix: server-sync conventionalLabels and small cleanups - Sync conventionalLabels to ~/.plannotator/config.json so custom label configurations survive cookie clears and remote/SSH sessions, matching the persistence story for conventionalComments. Stored as a parsed array on disk; serialized as JSON string in the local config store to match the cookie format. - Remove no-op intermediate variable in handleSubmitAnnotation; pass conventionalLabel/decorations directly with proper coalescing per call path (edit preserves null, add coalesces to undefined). - Use index-prefixed key in the picker label list to avoid React warnings if duplicate labels ever exist. For provenance purposes, this commit was AI assisted.
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
|
New: Code Review
Features
| Visual Plan Review | Built-in hook | Approve or deny agent plans with inline annotations |
| Plan Diff | Automatic | See what changed when the agent revises a plan |
| Code Review | /plannotator-review | View git diffs or remote PRs. Package annotations and ask AI about the code as you review. |
| Annotate Any File | /plannotator-annotate | Annotate any markdown file and send feedback to your agent |
| Annotate Last Message | /plannotator-last | Annotate 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
- Fully open source and self-hostable (see docs)
Install
Install for Claude Code
Install the plannotator command:
macOS / Linux / WSL:
curl -fsSL https://plannotator.ai/install.sh | bash
Windows PowerShell:
irm https://plannotator.ai/install.ps1 | iex
Then in Claude Code:
/plugin marketplace add backnotprop/plannotator
/plugin install plannotator@plannotator
# IMPORTANT: Restart Claude Code after plugin install
See apps/hook/README.md for detailed installation instructions including a manual hook approach.
Install for Copilot CLI
Install the plannotator command:
macOS / Linux / WSL:
curl -fsSL https://plannotator.ai/install.sh | bash
Windows 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 for details.
Install for Gemini CLI
Install the plannotator command:
macOS / Linux / WSL:
curl -fsSL https://plannotator.ai/install.sh | bash
Windows 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 for details.
Install for OpenCode
Add to your opencode.json:
{
"plugin": ["@plannotator/opencode@latest"]
}
Run the install script to get /plannotator-review:
curl -fsSL https://plannotator.ai/install.sh | bash
Windows:
irm https://plannotator.ai/install.ps1 | iex
This also clears any cached plugin versions. Then restart OpenCode.
Install for Pi
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 for full usage details, commands, and flags.
Install for Codex
Install the plannotator command:
macOS / Linux / WSL:
curl -fsSL https://plannotator.ai/install.sh | bash
Windows PowerShell:
irm https://plannotator.ai/install.ps1 | iex
Then in Codex — feedback flows back into the agent loop automatically:
!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 mode is not yet supported.
See apps/codex/README.md for details.
How It Works
When your AI agent finishes planning, Plannotator:
- Opens the Plannotator UI in your browser
- Lets you annotate the plan visually (delete, insert, replace, comment)
- Approve → Agent proceeds with implementation
- 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 (http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (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.