<p align="center"> <img src=".github/assets/banner.webp" alt="Plannotator" width="640" /> </p> <p align="center"> <strong>Everything you need to annotate and stay in the loop with your agents</strong><br/> <strong>Markdown Review • Code Review • HTML Artifacts</strong><br/> _{Annotate plans, specs, markdown, and HTML before implementation. Review diffs and PRs. Send feedback to your agent.} </p> <p align="center"> <img src=".github/assets/icons/amp.svg" alt="Amp" title="Amp" height="28" />&nbsp;&nbsp; <img src=".github/assets/icons/claude.svg" alt="Claude Code" title="Claude Code" height="28" />&nbsp;&nbsp; <img src=".github/assets/icons/codex.png" alt="Codex" title="Codex" height="28" />&nbsp;&nbsp; <picture> <source media="(prefers-color-scheme: dark)" srcset=".github/assets/icons/copilot-dark.svg" /> <img src=".github/assets/icons/copilot-light.svg" alt="Copilot CLI" title="Copilot CLI" height="28" /> </picture>&nbsp;&nbsp; <img src=".github/assets/icons/droid.png" alt="Droid" title="Droid" height="28" />&nbsp;&nbsp; <img src=".github/assets/icons/gemini.png" alt="Gemini CLI" title="Gemini CLI" height="28" />&nbsp;&nbsp; <img src=".github/assets/icons/kiro.svg" alt="Kiro" title="Kiro" height="28" />&nbsp;&nbsp; <picture> <source media="(prefers-color-scheme: dark)" srcset=".github/assets/icons/opencode-dark.svg" /> <img src=".github/assets/icons/opencode-light.svg" alt="OpenCode" title="OpenCode" height="28" /> </picture>&nbsp;&nbsp; <picture> <source media="(prefers-color-scheme: dark)" srcset=".github/assets/icons/pi-dark.svg" /> <img src=".github/assets/icons/pi-light.svg" alt="Pi" title="Pi" height="28" /> </picture> </p> <p align="center"> <a href="https://www.youtube.com/watch?v=a_AT7cEN_9I">Watch the og demo</a> · <a href="https://docs.plannotator.ai/open-source/start/installation">Installation guide</a> · <a href="https://plannotator.ai/">Official site</a> · <a href="https://github.com/plannotator/effective-html">Visual HTML Skills</a> · <a href="#herdr-annotate-plannotator-in-the-terminal">Herdr Annotate</a> </p>

Plannotator

Plannotator is a local, browser-based review surface for AI coding agents: Claude Code, Codex, Copilot CLI, Gemini CLI, OpenCode, Kiro, Droid, Amp, and Pi.

It plugs directly into your agent through its hooks and commands. When the agent proposes a plan, html, or finishes writing code, the work opens in your browser and you mark it up, comment, and send feedback directly to the agent for it to act on it.

<table> <tr> <td width="40%" valign="middle">

Review documents, plans, and agent messages

Annotate plans, specs, messages, html, then send the feedback to your agent.

<p><strong>Demo:</strong> <a href="https://youtu.be/XqFun9XCXPw">Plan review with Pi</a></p> </td> <td width="60%"> <img src=".github/assets/annotate.webp" alt="Annotate UI with inline annotations" width="100%" /> </td> </tr> <tr> <td width="40%" valign="middle">

Code Review

Review local changes or remote PRs. Comment on diffs, suggest code. Your comments go back to the agent. Works with Git, GitButler, Jujutsu (jj), Perforce (p4), GitHub, and GitLab.

</td> <td width="60%"> <img src=".github/assets/review.webp" alt="Code review with file tree and side-by-side diff" width="100%" /> </td> </tr> </table> <p align="center"> _{<strong>AI built in:</strong> ask AI about anything you're reviewing,<br/>or launch AI reviews that post comments to the diff.} </p>

Annotate HTML Artifacts

<p align="center"> <img src=".github/assets/html.webp" alt="Annotating a rendered HTML artifact" width="720" /> </p>

Herdr Annotate: Plannotator in the Terminal

<p align="center"> <a href="https://github.com/plannotator/herdr-annotate"> <img src=".github/assets/herdr-annotate-banner.svg" alt="Herdr Annotate" width="300" align="middle" /> </a> &nbsp;&nbsp; <img src=".github/assets/herdr-annotate.png" alt="Plannotator TUI annotating a markdown folder in the terminal" width="480" align="middle" /> </p>

Herdr Annotate brings Plannotator-style review to the terminal: annotate terminal text, review whole Markdown documents and your coding agent's replies inside Herdr, and send the feedback straight back to the agent as its next message. Works with Claude Code, Codex, Pi, Copilot CLI, and Droid replies. Annotations are saved in the Plannotator data directory, so terminal reviews and app reviews compound.

herdr plugin install plannotator/herdr-annotate

Prefer it standalone? Plannotator TUI powers the document review and runs without Herdr: brew install plannotator/tap/plannotator-tui.

---

Commands

_{On Codex, swap the slash commands for !plannotator … (e.g. !plannotator review) or the $plannotator-* skills.}

Annotate

/plannotator-annotate README.md                  # Local markdown file
/plannotator-annotate src/                       # Browse and annotate files in a folder
/plannotator-annotate https://docs.rs/…          # Fetch and annotate any URL
/plannotator-annotate report.html --render-html  # Render HTML as-is instead of converting
/plannotator-last                                # Annotate the agent's last message

Need a realistic document to try? Copy the product requirements document template and filled example as Markdown.

Code review

/plannotator-review                    # Review uncommitted changes
/plannotator-review <github-pr-url>    # Review a GitHub pull request
/plannotator-review <gitlab-mr-url>    # Review a GitLab merge request
plannotator review --gitbutler         # Review an active GitButler workspace
plannotator review --patch-file reading.diff # Review a static caller-supplied unified diff

GitButler users can review the whole workspace, one stack, or one branch layer. See the GitButler workflow guide.

Plan mode

No command needed. Plan mode is wired in through each harness's hooks. Any time your agent creates a plan, the markdown review surface opens for you.

CLI

plannotator sessions                   # List active Plannotator sessions
plannotator sessions --open 1          # Reopen a session in the browser
plannotator archive                    # Browse saved plan decisions read-only

---

Privacy and network behavior

Plannotator does not collect usage telemetry or analytics. Plans, diffs, annotations, drafts, history, and configuration stay local by default.

Each plan review, annotate, archive, share-portal, and code-review app surface checks GitHub for the latest Plannotator release when it loads. This sends no plan or review content and gives the Plannotator project owner no usage analytics, although GitHub receives an ordinary request. There is currently no opt-out setting for the release check. Local Git code review can also query the configured origin with git ls-remote to detect the default branch and a stale baseline; it does not send the local diff. That remote query runs when the review opens, when the page loads its diff, when you switch the diff type or base (including the "Diff out of date · Refresh" button), and when you press Fetch — never on a timer, so an idle review page makes no network calls. Turn it off entirely with plannotator review --no-git-remote-check, PLANNOTATOR_GIT_REMOTE_CHECK=0, or { "gitRemoteCheck": false } in ~/.plannotator/config.json; the compare target then comes from local refs only and the "behind GitHub" banner never appears.

Content leaves the local workflow only when a network feature needs it:

• URL annotation fetches the requested site, through Jina Reader by default for public pages or directly when Jina is disabled or unavailable.
• GitHub and GitLab review uses your authenticated CLI and Git remote to retrieve PR or MR data.
• Ask AI and review agents send the selected question and relevant plan, document, repository, or diff context to your configured provider.
• Sharing sends the complete link to whoever or whatever service you use to deliver it. Encrypted short links upload ciphertext to the paste service.
• Workspaces is a separate hosted product, so the open source app's local-storage model does not apply to content placed there.

The privacy policy documents these boundaries and the hosted website and waitlist data.

---

Link sharing

Open source asynchronous link sharing remains available for compatibility but is moving to deprecated support. Workspaces is the primary direction for team sharing. No removal date has been announced.

<p align="center"> <a href="https://room.plannotator.ai/"> <img src=".github/assets/sharing.png" alt="Sharing portal with upload options" width="720" /> </a> </p> <p align="center"> _{Legacy link-sharing demo: <a href="https://room.plannotator.ai/">room.plannotator.ai</a>} </p> <p align="center"> <a href="https://plannotator.ai/workspaces"> <img src=".github/assets/workspaces-cta.svg" alt="Workspaces is the team-sharing direction. Join the waitlist." height="44" /> </a> </p>

Share a plan with a teammate and they can annotate it themselves. Import their feedback and send it straight back to your agent.

Small markdown shares are compressed into the URL fragment. The fragment is not included in the browser's request to the share portal, but it is not encrypted. Anyone or any messaging service with the complete link can read the shared content. The portal host still receives ordinary request metadata.

Large markdown and raw HTML shares use a short-link service. The share payload is encrypted with AES-256-GCM before upload, the server stores only ciphertext, and the key is kept in the URL fragment rather than sent in the paste request. Anyone with the complete link can decrypt it. Hosted pastes expire after 7 days.

Same model as PrivateBin. The paste service is self-hostable.

Sharing can be disabled entirely with PLANNOTATOR_SHARE=disabled.

Workspaces is the primary path for hosted team collaboration.

---

Install

One installer covers almost every agent. It installs the plannotator binary, auto-detects your installed agents, and configures hooks, skills, and slash commands for each:

# macOS / Linux / WSL
curl -fsSL https://plannotator.ai/install.sh | bash

# Windows PowerShell
irm https://plannotator.ai/install.ps1 | iex

The installer downloads the binary from GitHub Releases. A full install can also contact GitHub for release resolution and agent files, Ataraxy-Labs/sem for the optional sem sidecar, and npm for Pi, selected extra skills, or the managed agent-terminal runtime. Pinning --version skips only GitHub API release resolution, not the release download. See the privacy policy for the complete network boundaries.

Want just the binary and nothing else? Pass --minimal (or export PLANNOTATOR_MINIMAL=1) to install only the plannotator binary to ~/.local/bin, skipping every skill, hook, slash command, and per-agent config:

curl -fsSL https://plannotator.ai/install.sh | bash -s -- --minimal

Then finish the step for your agent:

| Agent | After the installer | Details | |---|---|---| | Amp | Copy plannotator.ts into ~/.config/amp/plugins/, then plugins: reload. Workflows live in the command palette. | README | | Claude Code | /plugin marketplace add backnotprop/plannotator, then /plugin install plannotator@plannotator. Resta