Plannotator FAQ

Everything you need to know about using Plannotator to stay in the loop with your AI agents.

What is Plannotator?

What does Plannotator do? +

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.

What is Plannotator Inbox? +

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.

What agents does Plannotator support? +

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

How do I start using Plannotator? +

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.

Do I need to install anything on my agents? +

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).

What's the fastest way to see Plannotator in action? +

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

What can I annotate with Plannotator? +

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.
What is a "Guided Review"? +

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.

Can I use Plannotator for HTML and live sites? +

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.

What is Herdr Annotate? +

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.

What AI features are built into Plannotator? +

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

How does Plannotator handle my data and annotations? +

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.

What about the sharing feature? How does that work? +

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.

Is Plannotator secure? Are the binaries verified? +

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

How much does Plannotator cost? +

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.

What kind of support do you offer? +

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.
How do I uninstall Plannotator? +

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

Can I use Plannotator remotely or over SSH? +

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=1
  • export 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.

What integrations are available? +

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-review to review it with the full diff viewer.
Can I use Plannotator with Vim or other modal editors? +

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.