{ "markdown": "

\n \"Plannotator\"\n

\n\n\n\n

\n Everything you need to annotate and stay in the loop with your agents
\n Markdown Review • Code Review • HTML Artifacts
\n Annotate plans, specs, markdown, and HTML before implementation. Review diffs and PRs. Send feedback to your agent.\n

\n\n

\n \"Amp\"  \n \"Claude  \n \"Codex\"  \n \n \n \"Copilot\n   \n \"Droid\"  \n \"Gemini  \n \"Kiro\"  \n \n \n \"OpenCode\"\n   \n \n \n \"Pi\"\n \n

\n\n

\n Watch the og demo · Installation guide · Official site · Visual HTML Skills · Herdr Annotate\n

\n\n# Plannotator\n\nPlannotator is a local, browser-based review surface for AI coding agents: Claude Code, Codex, Copilot CLI, Gemini CLI, OpenCode, Kiro, Droid, Amp, and Pi. \n\n**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.\n\n\n\n\n\n\n\n\n\n\n
\n\n### Review documents, plans, and agent messages\n\nAnnotate plans, specs, messages, html, then send the feedback to your agent. \n\n

Demo: Plan review with Pi

\n\n		\n\n\"Annotate\n\n
\n\n### Code Review\n\nReview 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.\n\n\n\n\"Code\n\n
\n\n

\n AI built in: ask AI about anything you're reviewing,
or launch AI reviews that post comments to the diff.\n

\n\n## Annotate HTML Artifacts\n\n

\n \"Annotating\n

\n\n## Herdr Annotate: Plannotator in the Terminal\n\n

\n \n \"Herdr\n \n   \n \"Plannotator\n

\n\n[Herdr Annotate](https://github.com/plannotator/herdr-annotate) brings Plannotator-style review to the terminal: annotate terminal text, review whole Markdown documents and your coding agent's replies inside [Herdr](https://herdr.dev), 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.\n\n```\nherdr plugin install plannotator/herdr-annotate\n```\n\nPrefer it standalone? [Plannotator TUI](https://github.com/plannotator/plannotator-tui) powers the document review and runs without Herdr: `brew install plannotator/tap/plannotator-tui`.\n\n---\n\n## Commands\n\nOn Codex, swap the slash commands for `!plannotator …` (e.g. `!plannotator review`) or the `$plannotator-*` skills.\n\n### Annotate\n\n```\n/plannotator-annotate README.md # Local markdown file\n/plannotator-annotate src/ # Browse and annotate files in a folder\n/plannotator-annotate https://docs.rs/… # Fetch and annotate any URL\n/plannotator-annotate report.html --render-html # Render HTML as-is instead of converting\n/plannotator-last # Annotate the agent's last message\n```\n\nNeed a realistic document to try? Copy the [product requirements document template and filled example](https://docs.plannotator.ai/templates/product-requirements-document) as Markdown.\n\n### Code review\n\n```\n/plannotator-review # Review uncommitted changes\n/plannotator-review # Review a GitHub pull request\n/plannotator-review # Review a GitLab merge request\nplannotator review --gitbutler # Review an active GitButler workspace\n```\n\nGitButler users can review the whole workspace, one stack, or one branch layer. See the [GitButler workflow guide](https://docs.plannotator.ai/open-source/workflows/gitbutler).\n\n### Plan mode\n\nNo 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.\n\n### CLI\n\n```\nplannotator sessions # List active Plannotator sessions\nplannotator sessions --open 1 # Reopen a session in the browser\nplannotator archive # Browse saved plan decisions read-only\n```\n\n---\n\n## Privacy and network behavior\n\nPlannotator does not collect usage telemetry or analytics. Plans, diffs, annotations, drafts, history, and configuration stay local by default.\n\nEach 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. 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.\n\nContent leaves the local workflow only when a network feature needs it:\n\n- URL annotation fetches the requested site, through Jina Reader by default for public pages or directly when Jina is disabled or unavailable.\n- GitHub and GitLab review uses your authenticated CLI and Git remote to retrieve PR or MR data.\n- Ask AI and review agents send the selected question and relevant plan, document, repository, or diff context to your configured provider.\n- Sharing sends the complete link to whoever or whatever service you use to deliver it. Encrypted short links upload ciphertext to the paste service.\n- Workspaces is a separate hosted product, so the open source app's local-storage model does not apply to content placed there.\n\nThe [privacy policy](https://plannotator.ai/privacy) documents these boundaries and the hosted website and waitlist data.\n\n---\n\n## Link sharing\n\nOpen 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.\n\n

\n \n \"Sharing\n \n

\n\n

\n Legacy link-sharing demo: room.plannotator.ai\n

\n\n

\n \n \"Workspaces\n \n

\n\nShare a plan with a teammate and they can annotate it themselves. Import their feedback and send it straight back to your agent.\n\n**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.\n\n**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.\n\nSame model as [PrivateBin](https://privatebin.info/). The paste service is [self-hostable](https://docs.plannotator.ai/open-source/workflows/sharing).\n\nSharing can be disabled entirely with `PLANNOTATOR_SHARE=disabled`.\n\n[Workspaces](https://plannotator.ai/workspaces) is the primary path for hosted team collaboration.\n\n---\n\n## Install\n\nOne installer covers almost every agent. It installs the `plannotator` binary, auto-detects your installed agents, and configures hooks, skills, and slash commands for each:\n\n```bash\n# macOS / Linux / WSL\ncurl -fsSL https://plannotator.ai/install.sh | bash\n```\n\n```powershell\n# Windows PowerShell\nirm https://plannotator.ai/install.ps1 | iex\n```\n\nThe 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](https://plannotator.ai/privacy) for the complete network boundaries.\n\nWant 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:\n\n```bash\ncurl -fsSL https://plannotator.ai/install.sh | bash -s -- --minimal\n```\n\nThen finish the step for your agent:\n\n| Agent | After the installer | Details |\n|---|---|---|\n| **Amp** | Copy [`plannotator.ts`](apps/amp-plugin/plannotator.ts) into `~/.config/amp/plugins/`, then `plugins: reload`. Workflows live in the command palette. | [README](apps/amp-plugin/README.md) |\n| **Claude Code** | `/plugin marketplace add backnotprop/plannotator`, then `/plugin install plannotator@plannotator`. Restart Claude Code. | [README](apps/hook/README.md) |\n| **Codex** | Nothing. Plan review is enabled automatically via Codex's experimental `Stop` hook (macOS/Linux/WSL; on native Windows, Codex hooks are experimental and the installer prints manual setup steps). `$plannotator-review`, `$plannotator-annotate`, and `$plannotator-last` skills included. | [README](apps/codex/README.md) |\n| **Copilot CLI** | `/plugin marketplace add backnotprop/plannotator`, then `/plugin install plannotator-copilot@plannotator`. Restart. Plan review activates in plan mode (`Shift+Tab`). | [README](apps/copilot/README.md) |\n| **Droid** | `droid plugin marketplace add https://github.com/backnotprop/plannotator`, then `droid plugin install plannotator@plannotator`. Commands only, no plan interception yet. | [README](apps/droid-plugin/README.md) |\n| **Gemini CLI** | Nothing. The hook, policy, and slash commands are configured automatically. Requires Gemini CLI 0.36.0+. | [README](apps/gemini/README.md) |\n| **Kiro CLI** | Nothing. Skills and an example agent are installed automatically. Try `kiro-cli chat --agent plannotator`. | [README](apps/kiro-cli/README.md) |\n| **OpenCode** | Add `\"plugin\": [\"@plannotator/opencode@latest\"]` to `opencode.json`. Restart OpenCode. | [README](apps/opencode-plugin/README.md) |\n| **Pi** | Skip the installer. Just `pi install npm:@plannotator/pi-extension`. Start Pi with `--plan`, or toggle with `/plannotator-plan-mode`. | [README](apps/pi-extension/README.md) |\n\nFull walkthroughs live in the [installation docs](https://docs.plannotator.ai/open-source/start/installation).\n\n### Uninstall\n\nThe safe default removes recognized Plannotator-installed components and keeps\nyour local plans, history, drafts, guides, and settings:\n\n```bash\nplannotator uninstall\n```\n\nUse `--purge` for a full removal of known local Plannotator data as well:\n\n```bash\nplannotator uninstall --purge\n```\n\nPurge requires typing `purge` at the prompt and explains that the data is\nlocal-only: it is not stored on a Plannotator server and cannot be recovered.\nFor automation, pass `--yes` (or `-y`); non-interactive removal refuses to run\nwithout it. Use `--dry-run` to preview recognized work without making changes.\nHost integrations are always part of uninstall. If a broken or unavailable\nhost prevents safe cleanup, the command names the blocking plugin manager or\nconfiguration, gives exact manual cleanup instructions, and stops before\ndeleting the binary. Complete that cleanup and rerun uninstall.\nThese mechanics keep the ordinary confirmation default-negative, make the\nirreversible outcome require a stronger explicit word, and still give package\nmanagers and scripts a conventional non-interactive flag.\n\nThe command covers the conventional macOS, Linux, WSL, and Windows binary\nlocations; the managed `sem` sidecar and agent-terminal runtime; installer\nskills, commands, hooks, policies, caches, and recognizable Amp/Kiro files; and\ndetected Claude Code, Copilot CLI, Droid, Pi, and VS Code installations through\ntheir host CLIs. Shared JSONC settings are edited surgically, while strict JSON\nupdates preserve the file's indentation, line endings, and trailing-newline\nstyle. Custom\nor unrecognized files, separately installed optional skills, project-local\nintegrations, external plan-save locations, and invalid configs are preserved\n(malformed host config is a fail-safe error). If cleanup reports an error,\nthe CLI remains available for a safe retry, and its Windows PATH entry is\nretained or restored when possible. If PATH restoration itself fails, the\noutput gives the full CLI path for retry and asks for manual PATH repair.\nFor safety, purge refuses filesystem roots, the home directory, the shared\ntemporary directory, symlinked data directories, and non-directory data paths.\nExisting paths are compared by filesystem identity, so case aliases, symlinks,\nhardlinks, and bind mounts cannot bypass the root/home/ancestor checks.\nThat identity and every containment guard are revalidated after awaited host\ncommands, immediately before the synchronous data-removal block; a replaced\ndata directory is refused without touching either the old or replacement data.\nIf your dedicated data directory is symlinked, point `PLANNOTATOR_DATA_DIR` at\nits resolved target and retry.\n\nIf you installed only the standalone Pi extension and do not have the\n`plannotator` CLI, use `pi remove npm:@plannotator/pi-extension`.\n\n
\nClaude Code: manual hook setup (without the plugin system)\n\nAdd to `~/.claude/settings.json`:\n\n```json\n{\n \"hooks\": {\n \"PermissionRequest\": [\n {\n \"matcher\": \"ExitPlanMode\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"plannotator\",\n \"timeout\": 345600\n }\n ]\n }\n ]\n }\n}\n```\n\n
\n\n
\nPin a specific version\n\n```bash\ncurl -fsSL https://plannotator.ai/install.sh | bash -s -- --version vX.Y.Z\n```\n\n```powershell\n& ([scriptblock]::Create((irm https://plannotator.ai/install.ps1))) -Version vX.Y.Z\n```\n\n
\n\n### Try it\n\nThe fastest way to see what Plannotator does is to invoke it yourself, right now, from your agent:\n\n```\n/plannotator-last # annotate the agent's last reply\n/plannotator-review # review your current diff, PR-style\n/plannotator-annotate report.html # annotate any file, folder, or URL\n```\n\n(Slash commands in most agents; `$plannotator-*` skills in Codex, command palette in Amp.)\n\nPlan review needs no command at all. The next time your agent proposes a plan, it opens in your browser automatically.\n\n---\n\n## How it works\n\n### Plan review\n\n```\nAgent calls ExitPlanMode\n -> PermissionRequest hook fires\n -> Local server reads plan from hook input\n -> Browser opens with review UI\n -> You annotate and approve/deny\n -> Approve: agent proceeds\n -> Deny: structured feedback sent to agent\n -> Agent revises, plan diff shows what changed\n```\n\n### Code review\n\n```\nYou run /plannotator-review\n -> git diff captures changes (or PR fetched by URL)\n -> Browser opens with diff viewer\n -> Annotate lines, stage/unstage files\n -> Send feedback: returned to agent session\n -> Approve: \"LGTM\" sent\n```\n\n---\n\n## Integrations\n\n**VS Code**: Open plans in editor tabs, view diffs inline, add annotations from the editor gutter. Install from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=backnotprop.plannotator-webview).\n\n**Obsidian**: Auto-save approved plans to a vault with YAML frontmatter, tags from the plan title, and backlinks for graph connectivity. Configure in Plannotator's Settings panel.\n\n**Bear**: Save plans as Bear notes with nested tags and project metadata.\n\n**GitHub / GitLab**: Pass any PR or MR URL to `/plannotator-review` and review it with the full diff viewer, annotations, and file tree.\n\n---\n\n## Remote / SSH / devcontainer\n\nPlannotator auto-detects SSH sessions and switches to a fixed port. For explicit control:\n\n```bash\nexport PLANNOTATOR_REMOTE=1\nexport PLANNOTATOR_PORT=9999 # forward this port\n```\n\nVS Code devcontainers forward the port automatically (check the Ports tab). For raw SSH, add to `~/.ssh/config`:\n\n```\nHost your-server\n LocalForward 9999 localhost:9999\n```\n\n---\n\n## Security\n\nEvery released binary ships with a SHA256 sidecar. [SLSA provenance](https://slsa.dev/) attestations are available from v0.17.2. The current release workflow also attaches a CycloneDX JSON SBOM, evaluates it with a fresh Grype database before anything is attested or published, and creates a GitHub/Sigstore SBOM attestation for the shipped binaries and npm tarballs.\n\nThe SBOM is intentionally labeled as a release-wide Syft inventory of the monorepo's locked build inputs and dependencies. It is not an exact per-binary runtime inventory: Bun standalone executables do not expose their bundled JavaScript package metadata to Syft. The canonical [installation and verification docs](https://docs.plannotator.ai/open-source/start/installation#pin-or-verify-a-release) cover the existing installer path; the exact new SBOM commands are included below and must be copied to that Mintlify page before the first SBOM-enabled release.\n\nThe release gate rejects scanner-side ignored matches and treats unknown applicability conservatively as runtime when evaluating CISA KEV and fixable Critical findings. Its explicit Grype configuration, complete JSON results, database status, and repository policy decision remain available as workflow evidence.\n\nTo verify a released Linux x64 binary, its existing provenance, and the new SBOM evidence directly:\n\n```bash\ntag=vX.Y.Z\nversion=\"${tag#v}\"\nmkdir -p /tmp/plannotator-release-verify\ngh release download \"$tag\" --repo backnotprop/plannotator \\\n --pattern 'plannotator-linux-x64*' \\\n --pattern \"plannotator-${version}-release-sbom.cdx.json*\" \\\n --dir /tmp/plannotator-release-verify\n\n(cd /tmp/plannotator-release-verify && sha256sum --check plannotator-linux-x64.sha256)\n(cd /tmp/plannotator-release-verify && sha256sum --check \"plannotator-${version}-release-sbom.cdx.json.sha256\")\n\ngh attestation verify /tmp/plannotator-release-verify/plannotator-linux-x64 \\\n --repo backnotprop/plannotator --source-ref \"refs/tags/$tag\" \\\n --signer-workflow backnotprop/plannotator/.github/workflows/release.yml \\\n --predicate-type https://slsa.dev/provenance/v1\n\ngh attestation verify /tmp/plannotator-release-verify/plannotator-linux-x64 \\\n --repo backnotprop/plannotator --source-ref \"refs/tags/$tag\" \\\n --signer-workflow backnotprop/plannotator/.github/workflows/release.yml \\\n --predicate-type https://cyclonedx.org/bom\n```\n\nThese are separate claims over the same artifact digest: provenance identifies its builder/source/workflow, while the CycloneDX predicate describes the release-wide inventory. The release runbook also canonicalizes the downloaded SBOM and attested predicate with `jq -S` and compares them.\n\nTo verify on install:\n\n```bash\ncurl -fsSL https://plannotator.ai/install.sh | bash -s -- --verify-attestation\n```\n\nRequires the `gh` CLI, but no login: the installer fetches the attestation bundle from GitHub's public attestations API and verifies it with `gh attestation verify --bundle` (the extraction needs node, python3, or jq on PATH; gh's authenticated fetch is the fallback). Can also be set persistently in `~/.plannotator/config.json`:\n\n```json\n{ \"verifyAttestation\": true }\n```\n\nInstaller verification remains opt-in and verifies SLSA build provenance; normal installation does not require `gh`. See the [canonical installation docs](https://docs.plannotator.ai/open-source/start/installation#pin-or-verify-a-release) for details.\n\n---\n\n## Configuration\n\nSettings are saved in cookies (not localStorage) because each hook invocation runs on a random port. You can also set options through environment variables or `~/.plannotator/config.json`.\n\n### Optional Vim controls\n\nPlan and annotate views offer a default-off **Vim controls** profile under\n**Settings → Vim**. Once enabled, focus the document and use `j` / `k`\nto move one rendered block at a time. After `l` refines into a semantic level,\n`j` / `k` move among sibling rows, cells, or inline targets; `h` moves back to\nthe containing target. Refining past the deepest target enters text. `v`\nstarts characterwise Visual selection and\n`V` selects whole blocks. `Space` opens the normal annotation toolbar; `c`,\n`d`, `m`, and `t` select comment, redline, markup, and label actions. The same\nsemantic target graph drives pointer Pinpoint and keyboard navigation. Press\n`?` in the document for the contextual key reference. Inputs, dialogs,\neditors, `Tab`, and all pointer interactions retain their native behavior.\nThe document takes focus automatically when the page is otherwise neutral;\npress `Escape` from app chrome to return to it without clicking.\nAn additional default-off **Vim HUD** toggle appears beneath Vim controls. It\nuses the product-demo styling for the live target reticle and navigation\ncontext. Its bottom-right **Key panel** is independently hideable while the\nreticle remains active; `?` still opens the complete key map on demand. The\npanel shows recent handled keys, the current block/line/word/Visual phase, and\nthe command meaning without capturing text typed into comments or other\ncontrols.\nSee [Vim controls](docs/vim-controls.md) for the interaction contract and\nimplementation architecture.\n\n| Variable | Description |\n|---|---|\n| `PLANNOTATOR_REMOTE` | `1`/`true` for remote mode, `0`/`false` for local, unset for SSH auto-detection |\n| `PLANNOTATOR_PORT` | Fixed port (default: random locally, `19432` remote) |\n| `PLANNOTATOR_BROWSER` | Custom browser to open plans in |\n| `PLANNOTATOR_AI` | `disabled` to disable Ask AI, Review Agents, and Guided Review; the annotate agent terminal is separate |\n| `PLANNOTATOR_SHARE` | `disabled` to turn off URL sharing |\n| `PLANNOTATOR_SHARE_URL` | Custom base URL for share links (self-hosted portal) |\n| `PLANNOTATOR_PASTE_URL` | Base URL of the paste service API |\n| `PLANNOTATOR_ORIGIN` | Override agent detection: `claude-code`, `amp`, `droid`, `opencode`, `codex`, `copilot-cli`, `gemini-cli`, `kiro-cli`, `pi` |\n| `PLANNOTATOR_JINA` | `0`/`false` to disable Jina Reader for URL annotation |\n| `JINA_API_KEY` | Jina Reader API key for higher rate limits |\n| `PLANNOTATOR_DATA_DIR` | Base directory for Plannotator-managed files (plans, history, drafts, `config.json`). Default: `~/.plannotator`; if that directory doesn't exist and `$XDG_DATA_HOME` is set to an absolute path, `$XDG_DATA_HOME/plannotator` is used instead |\n\nPlannotator-managed files live under `~/.plannotator` by default. Some UI preferences are stored in functional browser cookies. To relocate the files (for example, for an XDG-clean home):\n\n```bash\nexport PLANNOTATOR_DATA_DIR=~/.local/share/plannotator\n```\n\n---\n\n## Development\n\n```bash\nbun install\n\nbun run dev:hook # Plan review server\nbun run dev:review # Code review editor\nbun run dev:marketing # Marketing site (plannotator.ai)\nbun run dev:vscode # VS Code extension (watch mode)\n```\n\n### Build\n\n```bash\nbun run build # Main targets (hook + opencode)\nbun run build:hook # Single-file HTML for the hook server\nbun run build:review # Code review editor\nbun run build:opencode # OpenCode plugin\nbun run build:vscode # VS Code extension\n```\n\nBuild order matters. The hook build copies pre-built HTML from `apps/review/dist/`. If you change UI code in `packages/ui/`, `packages/editor/`, or `packages/review-editor/`, rebuild the review app first:\n\n```bash\nbun run --cwd apps/review build && bun run build:hook\n```\n\nTest the plugin locally:\n\n```bash\nclaude --plugin-dir ./apps/hook\n```\n\nFull binary build:\n\n```bash\nbun run --cwd apps/review build && bun run build:hook && \\\n bun build apps/hook/server/index.ts --compile --outfile ~/.local/bin/plannotator\n```\n\n\n---\n\n## License\n\nCopyright 2025-2026 backnotprop\n\nDual-licensed under [Apache 2.0](LICENSE-APACHE) or [MIT](LICENSE-MIT) at your option.\n\nContributions are dual-licensed under the same terms unless you explicitly state otherwise.\n", "bytes": 26494, "sha": "655696f4ae874e142ff81dd7d582b28df4aceeef2825793450c48a835daf614f", "repo_slug": "backnotprop/plannotator", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/skl_backnotprop_plannotator_plannotator_comp_17c111f1/readme" }