Plannotator CLI Reference

Plannotator is a local, browser-based review layer for agent workflows: it opens plans, diffs, and documents in an annotation UI, the human marks them up, and the structured feedback comes back to you on stdout. It installs as a single plannotator binary plus per-host hooks, so plan review fires automatically when you exit plan mode; every other surface is launched explicitly, with the plannotator tool when you have one and with the CLI otherwise. A session runs on a random localhost port (fixed port 19432 in remote mode) and blocks until the reviewer submits feedback, approves, or closes the tab.

This skill is the knowledge layer. The plannotator-review, plannotator-annotate, and plannotator-last skills are thin launchers for the three most common actions; use this reference when you need to pick the right command or flags yourself.

If you have a plannotator tool, always use it

Check your tools before you run any command below. If you have a tool named plannotator (it can be listed with a prefix, for example mcp__plannotator__plannotator in Claude Code, and can need to be loaded through tool search before you call it), always call it instead of running plannotator annotate, plannotator review, or plannotator last. This includes approvals: call it with { "action": "annotate", "target": "<file>", "gate": true }, not --gate --json.

The tool returns at once. End your turn after you call it and wait: the reviewer's decision arrives later as a message. Do not also run the CLI, poll, or reopen the session.

Use the CLI only when you have no such tool, or for what the tool does not do: archive, guide, sessions, review flags other than --base and --gate, annotate flags other than --gate and --markdown, and strict gates that a script checks by exit code (--require-approval, --result-file). If your tool offers tailscale, pass tailscale: true instead of --tailscale.

Choose the command

Session model

Every review or annotate command starts a local web server, opens the browser, and blocks until the human decides. That can take minutes, or more than an hour for a large pull request. Launch it with a long (or no) command timeout, or in the background, then read stdout when the process exits. In Claude Code, a background command is stopped after 30 minutes unless you pass run_in_background with a longer timeout (up to 7200000 ms). Do not kill the process to "finish" a review; a session that ends without a decision reads as no feedback. If a session was stopped by a time limit, run the same command again: annotation drafts are restored.

Stdout is the interface, but its contract is command-specific. For annotate and its last-message variants:

• Plaintext (default): empty output on close, The user approved. on approve (an approval with a note prints an "Approved with Notes" message instead; treat the notes as guidance, not a change request), otherwise the feedback text. Address returned feedback in the same conversation.
• --json: one JSON record with decision (approved, dismissed, or annotated) and optional raw feedback. An approval may still carry notes in feedback; treat those as guidance, not a change request.
• --hook: hook-native output for real PostToolUse/Stop hook contexts only. Approve/close emits nothing (hook passes); annotations emit {"decision":"block","reason":"..."}. --hook implies the gate UI. Never use it for a normal interactive invocation.

plannotator <command> --help prints usage without launching anything. Bare plannotator is the hook entry point and expects hook JSON on stdin.

plannotator review

plannotator review [--git | --gitbutler] [--base <ref>] [--diff-type <type>] [--local | --no-local] [--patch-file <path | ->] [--no-git-remote-check] [--tailscale] [--gate] [--json] [DIRECTORY | PR_URL]

Reviews local VCS changes, or a pull request when a URL is given. Default stdout stays plaintext: the existing close message, approval prompt, or feedback.

With --json, direct review emits one record: { decision: 'approved' | 'annotated' | 'dismissed', message: string }. message is the CLI-rendered text exactly as default plaintext would print it, without the final console newline. It includes customized prompts and non-blocking approval-with-notes framing; a denial suffix is included only when annotations.length > 0, including in PR mode, not for zero-annotation platform status.

Classify the outcome only by decision, never by message text. Notes on an approved review are guidance, not a blocking change request. This rendered message contract is separate from the raw feedback JSON used by annotate and the unchanged opencode-review integration. --hook is annotate-only.

• VCS is auto-detected (JJ, GitButler, Git, and P4 where supported). --git forces plain Git; --gitbutler forces GitButler (requires the but CLI 0.21.0+). Running from a non-VCS parent folder that contains nested repos produces a combined workspace diff.
• The default diff is "everything a PR would show now": merge-base of the trunk vs the working tree plus untracked files. --base <ref> opens the session against a different compare target (branch, origin/<branch>, tag, or commit) and --diff-type <type> opens it in a different mode (since-base, merge-base, branch, uncommitted, staged, unstaged, last-commit, local-vs-remote, all). Both are session-only: the reviewer can change either in the UI, and neither writes the user's saved defaults.
• Reviewing one layer of a stacked branch? Pass --base <the branch below yours> — plannotator review --base feature/part-1 shows only what this layer adds, instead of everything since main.
• Both flags are git-only: they error on jj, GitButler, Perforce, multi-repo workspace reviews, and PR URLs (a PR's base comes from the pull request). A --base ref that does not resolve is a startup error naming near-match branches, never a silently wrong diff.
• --patch-file <path> reviews a static caller-supplied unified diff with no repository at all (use - to read it from stdin): the session serves the patch as-is with no file-system affordances that need a worktree. It cannot be combined with a PR/MR URL, --base, --diff-type, --git/--gitbutler, or --local/--no-local. Every working-tree affordance is off in that session (staging, hunk-context expansion, open-in-editor, code navigation, diff-type/base switching), and the endpoints behind them answer 400.
• Pass a directory to review another repo or worktree: plannotator review ../feature-worktree or plannotator review ./backend --diff-type last-commit. Paths resolve relative to the invoking directory; quote paths containing spaces. A directory selects the review workspace, not a file filter. Accepts one directory or PR URL; a directory cannot be combined with --patch-file. Invalid targets fail instead of falling back to the current repo.
• PR review (plannotator review https://github.com/owner/repo/pull/123, GitLab MR and Bitbucket Cloud PR URLs too) needs an authenticated gh or glab CLI; Bitbucket Cloud (https://bitbucket.org/<workspace>/<repo>/pull-requests/<id>) instead needs an Atlassian API token in PLANNOTATOR_BITBUCKET_TOKEN (plus PLANNOTATOR_BITBUCKET_EMAIL). --local (the default) builds a local checkout of the PR head in the background for full file access; --no-local skips it and reviews the platform diff only.
• --no-git-remote-check stops the session contacting the git remote at all: no git ls-remote for the default branch or the "behind GitHub" baseline check. The compare target then comes from local refs only and the staleness banner never shows, which also takes away its one-click Fetch button (the /api/fetch-base endpoint stays available); fetching from a terminal is unaffected. Use it when a remote probe is expensive or intrusive — most sharply when SSH authentication is backed by a hardware token, where each probe is a physical touch prompt. The same opt-out is available session-wide as PLANNOTATOR_GIT_REMOTE_CHECK=0 or { "gitRemoteCheck": false } in ~/.plannotator/config.json (the flag beats the env var, which beats the config key). Without it the remote is queried when the review opens, on diff load, on a diff-type/base switch, and on Fetch — never on a timer.
• --tailscale publishes the loopback session over the user's tailnet via tailscale serve (HTTPS, never public) and prints the URL with a QR code. A publish failure exits nonzero instead of leaving the server hanging. Use it only when the user asks to open the review on another device (a phone, a tablet) or over Tailscale. With a plannotator tool that offers it, pass tailscale: true (annotate, review, last) instead: "Ask this session" then keeps working on the tailnet for the Tailscale login that owns this computer.
• --gate says you are waiting for the reviewer's sign-off before going on (committing, opening the PR): a bare Approve then reaches you too. With a plannotator tool, pass gate: true on the review action instead.

plannotator annotate

plannotator annotate <target> [--markdown] [--no-jina] [--app | --static] [--render-html] [--tailscale] [--gate] [--json] [--hook]

Opens one document, page, or app in the annotation UI and returns the human's annotations on stdout.

Plain annotate is feedback-only: it shows Close but no Approve button. When the user asks to review, approve, accept, or gate a generated plan/spec/document saved as a file, call the plannotator tool with "gate": true if you have it; otherwise always add --gate --json. Do not tell the user they can approve a plain annotate session. If the plan is being handed off through the host agent's native plan flow, do not launch annotate; let the plan-exit hook open the approval UI automatically.

Targets:

• Markdown and text files: .md, .mdx, .txt.
• Plain-text config and data files, rendered as text: .yaml, .yml, .json, .jsonc, .json5, .toml, .ini, .cfg, .conf, .properties, .csv, .tsv, .log, .xml, .env.example. .env itself is deliberately refused (it commonly holds secrets, and annotate history copies file contents). Source-code files belong to plannotator review, not annotate.
• Diagram sources, opened in the full diagram viewer (zoom, pan, popout, click a node/edge/cluster to comment): .mmd, .mermaid (Mermaid) and .dot, .gv (Graphviz). The file is the whole diagram — no fence needed — and comments carry the part's id plus its real file line.
• HTML files (.html, .htm): rendered as the raw page by default; --markdown converts to markdown instead. --render-html is accepted for compatibility; raw rendering is already the default.
• URLs (https://...): fetched and converted via Jina Reader by default; --no-jina uses plain fetch plus Turndown instead.
• Running local apps: a loopback http://localhost:PORT/ URL whose probe returns HTML opens in live-app mode (annotate the real running page). --app forces live mode and fails loudly when it cannot apply; --static forces the classic conversion pipeline. Non-loopback URLs always use the conversion pipeline.
• Folders: plannotator annotate docs/ opens a file browser over the folder's supported files.
• Several files: plannotator annotate spec.md mock.html notes.md opens them as one review, in the order given, with one decision. Every argument must be an existing file named by its path (no prose, URLs or folders among them). With the plannotator tool, pass the list as target.

Single files are capped at 2MB. Files are read from disk at stable project paths; keep the reviewed source where it lives.

Argument tolerance: extra words are fine (plannotator annotate look at notes.md please opens notes.md), but two resolvable targets mixed with prose, a URL or a folder is an error naming them, and an unrecognized dashed token disables the tolerance so flag typos fail loudly. When nothing resolves in a plain multi-word invocation, the CLI prints an agent-addressed handoff on stdout and exits 0: read it, work out the concrete target, and re-run with that exact path or URL.

Strict gates and exit codes

For a machine-checkable approval gate, add --gate --json plus one or both strict flags:

plannotator annotate report.md --gate --json --require-approval --result-file /tmp/decision.json

• --require-approval: exit code reports the human outcome.
• --result-file <path>: the stdout decision JSON is also published atomically to <path>. The parent directory must exist and the file must not; results resolve from the invocation cwd.

Exit codes under a strict flag (grep convention):

Without strict flags, startup failures exit 1 and the exit code carries no decision; parse the output instead. Both strict flags require --gate --json and reject --hook.

plannotator annotate-last

plannotator annotate-last [--stdin] [--tailscale] [--gate] [--json] [--hook]
plannotator last

Opens the latest rendered assistant message from the current agent session in the annotation UI (last is an alias). The session log is discovered per host automatically; --stdin reads the content from stdin instead.

Do not print a commentary or status message immediately before running it: the command targets the latest rendered assistant message, so a preamble becomes the thing being annotated.

plannotator copilot-last

plannotator copilot-last [--gate] [--json] [--hook]

The annotate-last variant for live GitHub Copilot CLI sessions (reads Copilot's session-state events). Normally invoked by the Copilot plugin's /plannotator-last command; use it only inside a Copilot CLI session.

plannotator archive

plannotator archive

Opens a read-only browser over saved plan decisions (approved/denied badges) from the Plannotator data directory. No feedback comes back; the session ends when the user clicks Done.

plannotator guide

plannotator guide list
plannotator guide export --id <savedGuideId> [--out <file.html>]
plannotator guide export --guide <guide.json> --patch <diff.patch> [--out <file.html>]
plannotator guide export --snapshot <snapshot.json> [--out <file.html>]
plannotator guide share --id <savedGuideId> [--public] [--ttl <7d|24h|30m|3600>] [--json]
plannotator guide unshare <id> --token <deleteToken>

Guided Reviews are AI-generated walkthroughs of a diff, produced inside the code review UI. The CLI works with saved ones:

• list shows guides Plannotator has persisted for the current repo.
• export writes one portable, self-contained HTML file (the viewer loads from guides.show). --guide + --patch exports a guide you authored yourself against a unified diff (--patch - reads stdin; validation is strict and names any file the guide references that the patch lacks). --out - writes to stdout. --viewer-url overrides the pinned viewer base.
• share uploads the guide and prints a link. Encrypted by default: the key lives only in the URL fragment and the host stores ciphertext. --public stores it unencrypted so chat apps can unfurl a preview. --ttl sets an expiry; otherwise the link stays until unshare. A saved guide records its link, and a second share --id refuses rather than orphaning the first link's delete token.
• unshare <id> --token <t> removes a link using the delete token printed at share time.

plannotator sessions

plannotator sessions [--open [N]] [--clean] [--json]

Lists active Plannotator server sessions, each with its full target (absolute path, URL, PR URL or reviewed directory) and, for a review a host opened, its pn- id. --open reopens session N (default 1) in the browser, useful when a tab was closed mid-review. --clean drops stale entries. --json prints the list as a JSON array on stdout.

plannotator inbox

plannotator inbox [--background | --no-open | --open] [--tailscale]
plannotator inbox mcp

The Plannotator Inbox is one local window per machine where you leave the person messages, :::question blocks they answer with a click, files to annotate and guided reviews. Nothing blocks: you send, then keep working or end your turn.

• Use it when the person may not be watching this chat: a decision only they can make (a :::question block, then go on with work that does not depend on it), long work you finished (one short summary, with the files to look at in attachments), or when they ask. Ask in the chat when they are there, and do not send routine progress. Use a review (plan review, annotate, review) when you need a decision on this document or diff before you go on.
• If you have a plannotator_inbox tool, use it; otherwise use the stdio MCP server plannotator inbox mcp. With the tool, the person's reply arrives in your session by itself, so end your turn instead of waiting.
• Run plannotator inbox --help once and read it before your first use: it is the full guide (tools and arguments, threads, where replies go, question syntax, replacing questions, connecting other agents).
• Never run plannotator inbox just to send: calls start a stopped Inbox in the background, and bare plannotator inbox opens the window for the person. --tailscale is the person's choice; never add it.
• When the person asks where their Inbox is, or to open it (a closed tab), run plannotator inbox --open: it opens the window in their browser (starting the Inbox in the background if needed), prints its address on stdout and returns at once. Tell them the address.

plannotator card

plannotator card <create|move|say|link|ship|drop|list> ...

Only while the person has turned the Inbox's Board on (Settings → General); it is off by default, and then every call answers board_off and writes nothing, so use it only when your inbox tool lists card or the person asks. The Board holds one card per piece of work that outlasts a reply, in the column of its stage (backlog, designing, your_look, building, your_review, shipped). Use the card action of a plannotator_inbox tool when you have one; this CLI is the same call from a shell. plannotator card --help gives the arguments, and plannotator inbox --help its card section while the Board is on. The icebox is the person's only.

Other subcommands

plannotator setup-goal <interview|facts> <bundle.json | -> [--json]
plannotator update [--check]
plannotator uninstall [--purge] [--yes] [--dry-run]
plannotator improve-context

• setup-goal opens the interview or facts-acceptance UI for /goal workflows; it is driven by the plannotator-setup-goal skill and takes a bundle JSON (- reads stdin). Do not hand-build bundles.
• update installs the newest release now (the install script, with the choices from the last install); --check only reports whether one exists. Run it only when the person asks you to update Plannotator: it replaces the binary. Exit 0 up to date or updated, 1 failed, 2 usage, 130 interrupted.
• uninstall removes Plannotator-installed components (--purge also deletes local data; --yes is required without a TTY; --dry-run previews).
• improve-context and install-runtime are internal integration commands (hook plumbing and managed runtime install). Never run improve-context directly; plannotator install-runtime agent-terminal exists for reinstalling the optional annotate-terminal runtime and is normally run by the installer.
• Additional host-internal subcommands (the opencode-* and copilot-plan family) are invoked by their plugins, not by you.

Environment variables that change behavior

Posting annotations into a live session

A running plan-review session exposes a small HTTP API on its base URL for external annotations: POST /api/external-annotations adds inline annotations the reviewer sees immediately, with PATCH/DELETE for updates and an SSE stream at /api/external-annotations/stream. The UI's "copy agent instructions" action puts the full API contract for the current session, with the correct base URL, on the clipboard for handing to an agent or script. If the user pastes such instructions, follow them; do not invent endpoints beyond that contract.

Asking the reviewer questions

Ask what only the reviewer can decide as a question block. Answers come back at the top of their feedback ("Answers to your questions", then "Unanswered").

:::question
Where should we keep the edit that loses a sync conflict?

When two devices edit one note offline, the later save wins and the other edit is lost. Local storage keeps it with no server work.

- [ ] Local only, purged after 30 days — cheap, no server change
- [ ] Server-side per user — survives reinstall, needs a retention policy
- [ ] Nowhere — accept silent loss for v1

Recommended: Local only, purged after 30 days
:::

• :::question picks one choice, :::question-multi any number, :::question-text free text (so does a block with no choices).
• The first line is the question; the lines after it are context. Never send a bare question: the reviewer switches in cold, thinks at the level of the product, and does not know what you know.
  • Say what the choice affects, what you know or tried, and why you recommend it, so they can decide without opening anything else.
  • Be terse: one to three short sentences, plain words, no jargon or internal names.
  • Add a screenshot (![alt](path)) for anything visual.
  • Link a file that shows it better (a plan, a mock): [the mock](mock.html). In the Inbox, attach it too; the link opens it beside the thread.
• Choices: - [ ] label, optionally - [ ] label — why. The reviewer can also answer "Other", add a note, or skip.
• Recommended: <label> marks yours (A, B and C on :::question-multi); other text shows as one more answer, tagged Recommended.
• Ask only what you cannot decide alone, about 8 a round at most. Do not ask rhetorical questions or questions the codebase answers.
• - [x] marks a settled choice. On resubmit, check the chosen answer, or drop the block and state the decision in prose.
• Leave blank lines between the parts so the block reads well on GitHub.
• Each answer comes back under its question (### Q2. <question> (line N)) as Answer: <choice>, marked (your recommendation) when the reviewer took yours, or as Other: …, free text in a quote, or Skipped, plus any Note:. A question you marked - [x] is settled and only comes back if the reviewer changed it or added a note.
• In the Inbox, withdraw your own questions that are still open (read_thread state open or picked) as the thread moves on: when a newer message replaces them, makes them moot or follows up on them, or the person's reply settled them in words, name them in supersedes (or a Replaces: line) so they stop keeping the thread at the top of the person's list.

Do not

• Do not run plannotator annotate, review, or last through a shell when you have a plannotator tool; call the tool.
• Do not parse or scrape the browser UI's HTML; the CLI's stdout (and the documented HTTP API above) is the whole contract.
• Do not use --hook outside a real hook context; use --json when you need structured output.
• Do not run bare plannotator interactively; it is the hook entry point.
• Do not guess flags. Run plannotator <command> --help when unsure; unknown dashed tokens make annotate fail on purpose.
• Do not point plannotator annotate at source-code files or .env files; code goes through plannotator review, and .env is refused.
• Do not start a strict gate (--require-approval) unless a human is actually there to review; the session blocks until they act.