What is Plannotator?
Plannotator is a browser-based review surface for AI coding agents and assistants. It plugs directly into your agent through plugins, hooks, and commands. When an agent proposes a decision, plan, HTML, or finishes working, Plannotator opens in your browser, allowing you to annotate, comment, and send feedback directly back to the agent for it to act on. It helps you stay in the loop and guide your AI collaborators effectively.
Plannotator Inbox is a centralized local window where your agents leave you messages, questions, files, and guided reviews while they continue to work. You can answer questions with a click, annotate files, and send your feedback when you're ready. It doesn't hold an agent session open, and your reply goes back to the specific session that asked, allowing for asynchronous collaboration with AI agents.
Plannotator works with a wide range of AI coding agents and personal assistants, including:
- Coding Agents: Claude Code, Codex, Copilot CLI, Gemini CLI, OpenCode, Kiro, Droid, Amp, DeepSeek Harness, and Pi.
- Personal Assistants: Grok Bot, Muse, Hermes, and OpenClaw (via Plannotator Inbox and MCP).
Getting Started
Getting started is easy with our one-command installer:
- For macOS / Linux / WSL:
curl -fsSL https://plannotator.ai/install.sh | bash - For Windows PowerShell:
irm https://plannotator.ai/install.ps1 | iex
The installer automatically detects your installed agents and configures the necessary hooks, skills, and slash commands for each. After installation, you can start annotating immediately by using commands like /plannotator-last in your agent's chat interface.
Yes, the installer guides you through the setup for each specific agent. For example, for Claude Code, you'll run /plugin marketplace add backnotprop/plannotator and then /plugin install plannotator@plannotator. For Pi, you'll run pi install npm:@plannotator/pi-extension. The installer handles the binary installation, and then provides the specific steps for your chosen agent(s).
The fastest way is to invoke it directly from your agent's chat interface using slash commands:
/plannotator-last- Annotate the agent's last reply/plannotator-review- Review your current diff, PR-style/plannotator-annotate report.html- Annotate any file, folder, or URL
For plan review, no command is needed. The next time your agent proposes a plan, Plannotator will open in your browser automatically.
Features & Functionality
You can annotate a wide variety of content types:
- Documents: Markdown files, product requirements, technical specs, and other text-based plans.
- Code: Review diffs and pull requests with a powerful side-by-side diff viewer.
- HTML Artifacts: Rendered HTML files or any site running on your local machine.
- Agent Messages: The last message from your agent, allowing for direct feedback on its output.
- URLs: Any public webpage, which Plannotator will fetch and render for annotation.
Guided Review is an AI-powered feature that helps you understand large code changes. When reviewing a diff, you can press the "Guide" button (or use the keyboard shortcut Cmd/Ctrl+Shift+G). An AI agent then automatically sorts the diff into logical chapters—starting with the most important parts of the change, followed by its effects, and then the connecting code. Each chapter provides a short overview next to the real diff, making it easier to review and comment on complex changes.
Yes. You can annotate rendered HTML files or any site running on your machine. Use the command plannotator annotate http://localhost:5173 (or your local server's address). Plannotator opens a local proxy, allowing you to comment on the real page while hot reload continues to work seamlessly.
Herdr Annotate brings Plannotator-style review directly into your terminal. It allows you to annotate terminal text, review whole Markdown documents, and your coding agent's replies inside the [Herdr](https://herdr.dev) terminal interface. Annotations are saved in the Plannotator data directory, so terminal reviews and in-app reviews compound. You can install it with herdr plugin install plannotator/herdr-annotate.
Plannotator includes several AI-powered features to enhance your workflow:
- Ask AI: You can ask AI questions about any document or code you're reviewing directly within the Plannotator interface.
- AI-Powered Comments: Launch AI reviews that automatically generate and post comments to your diffs.
- Guided Reviews: As mentioned above, this feature uses AI to structure and explain complex code changes.
- AI Review Agents: Specific AI agents are available to help you review different types of content more effectively.
You can disable these AI features by setting the environment variable PLANNOTATOR_AI=disabled.
Security & Data
Your annotations and plans are stored locally on your machine by default, in the ~/.plannotator directory. This ensures your data remains private and under your control. UI preferences are stored in browser cookies, as each hook invocation runs on a random port. You can change the data directory location by setting the PLANNOTATOR_DATA_DIR environment variable.
Sharing allows you to send a plan as a link to a teammate. They can then annotate it, and you can import their feedback for your agent. Small shares live directly in the URL, while larger ones are encrypted before upload to a server and automatically expire after 7 days for security. Anyone with the full link can read the shared content. You can disable sharing completely by setting the environment variable PLANNOTATOR_SHARE=disabled.
Yes, security is a top priority. Every released binary ships with a SHA256 checksum for verification. Starting from version 0.17.2, releases include SLSA provenance attestations. The release process also generates a CycloneDX JSON SBOM (Software Bill of Materials), which is scanned for vulnerabilities before publication. You can verify a binary's integrity and provenance using the gh CLI. The installer also offers an optional --verify-attestation flag to automatically verify the download upon installation.
Support & Pricing
Plannotator offers a range of plans to suit different needs. The core product is available with a free tier for individual use. For teams and advanced features, we offer paid plans. For the most up-to-date information on pricing and features, please visit our official site: plannotator.ai.
We offer several avenues for support:
- Documentation: Our comprehensive documentation at docs.plannotator.ai covers installation, usage, and troubleshooting.
- Community: Join our community to connect with other users and share tips.
- Direct Support: For paid plans, we offer direct email support to help resolve any issues you encounter.
We provide a safe uninstall command that removes recognized Plannotator-installed components while preserving your local plans, history, drafts, guides, and settings. Simply run:
plannotator uninstall
If you wish to remove all Plannotator data, including your saved files, use the --purge flag:
plannotator uninstall --purge
The command will guide you through the process and explain what is being removed.
Advanced Use Cases
Yes. Plannotator can auto-detect SSH sessions and switch to a fixed port for remote access. To use it remotely, set the environment variables:
export PLANNOTATOR_REMOTE=1export PLANNOTATOR_PORT=9999(or your chosen port)
You'll need to forward this port to your local machine. In VS Code devcontainers, this is handled automatically. For raw SSH, you can add a configuration to your ~/.ssh/config file to set up the port forwarding.
Plannotator offers several integrations to fit into your existing workflow:
- VS Code: Open plans in editor tabs, view diffs inline, and add annotations from the editor gutter.
- Obsidian: Auto-save approved plans to a vault with YAML frontmatter and tags.
- Bear: Save plans as Bear notes with nested tags and project metadata.
- Notion: Save plans as Markdown child pages under a shared Notion page.
- GitHub / GitLab: Pass any PR or MR URL to
/plannotator-reviewto review it with the full diff viewer.
Yes. Plannotator offers an optional "Vim controls" profile in its settings. Once enabled, you can navigate and annotate using familiar Vim-style keybindings like j and k to move between blocks, l to refine into a semantic level, and v for visual selection. This allows for efficient, keyboard-driven annotation without leaving your preferred workflow.