backnotprop/plannotator v0.28.0

on GitHub

Follow @plannotator on X for updates

What's New in v0.28.0

Plannotator now connects to the agent session that opened it. Ask AI can be answered by your Claude Code, Pi, or OpenCode 2 session instead of a separate AI, and in Claude Code and Pi the agent no longer sits waiting while you review: your decision arrives later as a message. This release has 24 pull requests, two of them from community contributors, including one first-time contributor.

Ask this session

When Plannotator was opened by Claude Code, Pi, or OpenCode 2, a question you ask in Ask AI goes to that agent session. It shows up in the agent's chat as a real turn, the agent answers with the context it already has and can use its own tools, and the answer streams back into the Ask AI panel. The panel reads "Ask this session · Claude Code" (or Pi, or OpenCode).

When a session is connected, it is the only Ask AI option, so there is no provider or model picker. A provider you saved earlier is left alone and still applies in sessions without a connection, and Review Agents, Code Tour, and Guided Review keep their own model pickers. If the agent is busy, you can choose "Ask when it finishes" or "Interrupt and ask now". Stopping a question cancels only that question; Plannotator never interrupts a turn on its own. If the session has ended, Ask AI says it can no longer reach it.

Where it works:

• Claude Code: plan review, code review, annotate, and /plannotator-last, through the Claude Code mod described below.
• Pi: plan review, code review, annotate, and /plannotator-last.
• OpenCode 2: code review, annotate, and /plannotator-last as real turns. During plan review OpenCode is still waiting on submit_plan, so Ask AI gives a "Quick answer from this session" from the conversation, without tools, and writes nothing to the transcript.
• Not connected: OpenCode 1, Claude Code without the mod, remote mode, and --tailscale sessions. These keep the separate AI providers exactly as before.

The first time you open Plannotator from a connected session, a short panel with a demo video explains the feature. It appears once, only when the session really is connected, and only before you start working on the page. It links to the Ask this session guide.

(#1668, #1671, #1685, #1690)

Claude Code no longer waits while you review

On Claude Code 2.1.287 and later, in the interactive terminal, the Plannotator plugin now runs as a Claude Code mod, and it is on by default. Plan review, /plannotator-review, /plannotator-annotate, and /plannotator-last open in the browser and hand control back to Claude right away. When you decide, the decision arrives in the chat as a message from the plannotator plugin, and Claude acts on it. While the review is open you can keep talking to Claude, and Ask this session works.

Plan review under the mod works like this:

• When Claude calls ExitPlanMode, the review opens and Claude is told the plan is not approved yet. Plan mode stays on.
• If Claude revises the plan while the review is open, the same tab updates to the new version and keeps your comments. A decision made on an older version is refused, and the tab loads the new one so you can decide again.
• After you approve, Claude calls ExitPlanMode once more and proceeds with the exact text you approved, in the permission mode you picked.
• Denials and answered questions arrive as messages, using the same prompts as before.

Decisions with nothing to send (Done with no comments, an LGTM, Close) only log a line and do not start a turn. Feedback over 12 KB is saved to a file that Claude is told to read. /plannotator-last keeps its picker of recent messages, so you can still annotate an earlier reply. Review servers keep running if Claude Code exits: run claude --continue or --resume, and the decision is delivered into that session.

Older Claude Code, -p and SDK sessions, and Windows keep the classic flow, unchanged. To turn the mod off, set PLANNOTATOR_CLAUDE_MOD=0 or add { "claudeCodeMod": false } to ~/.plannotator/config.json; it takes effect the next time Claude Code starts. The plugin and the plannotator binary update separately, so update both (see Install / Update below). With an older binary, plan review falls back to the classic blocking review and Claude Code shows one line asking you to update; review, annotate, and last still open, without Ask this session.

(#1672, #1686, #1684, #1691)

Claude opens Plannotator through a tool instead of Bash

Asking Claude to "open this in plannotator" used to make it run the CLI through Bash, which blocked Claude and left Ask AI on a separate AI. Under the mod, Claude now has a plannotator tool for annotate, review, and last. It opens Plannotator exactly the way the slash commands do and returns at once, and the decision arrives later as a message. With gate: true, an approval is sent back too, so Claude can continue once you sign off. The plannotator skill now tells agents to always use the tool when they have it, including for approvals. The installer refreshes the skill.

Claude still sometimes reaches for the CLI. When it runs a simple command such as plannotator annotate notes.md --gate --json in the main session, the mod now opens it the same way the tool does. Only plain annotate <file> (with --gate or --markdown), review (with an optional target and --base), and last are taken over. Anything with other flags, shell syntax, an environment prefix, or a path to a dev build runs the real CLI, so scripts that depend on --require-approval or --result-file exit codes keep working. Commands from subagents always run as written.

Strict gate flags don't fit a slash command, because nothing would read the result. Typing /plannotator-annotate notes.md --require-approval (or --result-file, or --hook) under the mod now opens nothing and tells you to run that command in a terminal. Before, the reviewer's feedback was lost.

(#1673, #1687, #1688, #1692)

Pi plan review no longer blocks the session

On Pi, plannotator_submit_plan now returns as soon as the review opens, and the agent ends its turn. Your decision arrives later as a session message. An approval switches Pi to executing first, then sends the approval. A denial or answered questions come back as feedback. Planning restrictions stay in place until you approve, so nothing gets implemented early.

If the agent resubmits while the review is open, the same tab updates to the new version and keeps your comments, as in Claude Code. Esc no longer cancels a plan review; leave plan mode to abandon it. Ask this session works during plan review.

(#1670)

Claude Code plan review shows the plan Claude just wrote

Claude Code plan review sometimes opened the previous version of a plan, usually the one you had just denied. This happened when Claude edited the plan file and called ExitPlanMode in the same message, which recent models often do after a denial. Claude Code captured the plan text before the edit ran, so the review, the version history, and the approval all recorded the old text.

Plannotator now reads Claude's plan file when Claude Code sends its path and the file is an absolute .md file under 2 MB, and falls back to the inline text otherwise. On approval, Claude proceeds with the plan you reviewed. Claude Code 2.1.285 fixed the cause upstream, and this covers everyone on older versions.

(#1667, by @workflow)

Question cards

• Pinpoint targets what you click. In Pinpoint mode, hovering or clicking any choice in a question card highlighted the question's prompt instead, and recorded no answer. This had been the case since question cards shipped in v0.27.23. A pinpoint click now pins the prompt, the context, or the choice you clicked, and clicking a radio or checkbox answers (#1683).
• Agents give questions some context. The question guidance in the plannotator skill now tells agents that a sentence or two of context helps reviewers answer faster, and that the context can include an image for visual questions (#1674).
• Decision questions. A Decision: when answered line, or Decision: [statement](https://...), marks a question whose answer becomes a decision, and the card shows a decision tag for it (#1664).

Image links in annotated HTML open in the lightbox

In a raw-HTML annotate session, a link to a local image, such as a thumbnail linking to a full-size render, used to show a "Can't open" toast. In Interact mode it now opens in the image lightbox; with pinpoint armed, the click still pins the element. Only images inside the page's own folder open this way, so nothing becomes readable that the page could not already load. While the lightbox is open, Esc closes it and Mod+Enter cannot submit a decision behind it, which also fixes the lightbox in markdown documents.

(#1676)

Installer fixes

• The Claude Code mod is no longer stripped on install. Every installer run overwrote hooks.json in Claude Code's marketplace copy of the repo with an old hard-coded version, and the next plugin install copied that file, without the mod, into the installed plugin. The installers no longer touch that file. If an earlier installer had rewritten it, they restore it from git, but only when it matches a shape an installer wrote, so your own edits are kept (#1689).
• OpenCode 2 picks up the new plugin. The installers cleared only OpenCode 1's plugin cache. They now also clear OpenCode 2's cache under ~/.cache/opencode/npm/ (or $XDG_CACHE_HOME), so re-running the installer loads the new version (#1689).
• install.cmd adds Plannotator to your PATH. The Claude Code hook now runs a bare plannotator, so it needs to be on PATH. install.ps1 already added the install folder to the user PATH; install.cmd only printed advice and now adds it too, without creating duplicates (#1692).

For embedders: @plannotator/ui and @plannotator/core

• Apache-2.0. Both packages now declare the Apache-2.0 license and ship its text (#1675).
• DiffFileTree. A read-only file tree to put beside your own diff list. It is the code review file tree itself, moved into @plannotator/ui, with keyboard navigation and tree ARIA roles. Plannotator's review renders from the same parts and looks the same as before (#1678).
• HTML frame height and fence themes. Hosts that size the HTML viewer to its content got a frame cut short when a page's first or last element had a margin; the measured height now includes those margins. A new fenceTheme option on configurePlannotatorUI lets a host choose the code block theme (#1677).
• Question hooks. findQuestionBlocks, a new @plannotator/core/markdown-structure subpath, a footer slot for host actions on question cards, and an explicit save mode for answers (#1664).

These shipped as @plannotator/core 0.25.9 / @plannotator/ui 0.49.0 and @plannotator/core 0.25.10 / @plannotator/ui 0.50.0 (#1682). Note for the next @plannotator/ui release: the "Ask a separate AI instead" fallback helpers that shipped in 0.50.0 (resolveSessionBridgeFallback, findUsableSessionBridge, sessionAskFallbackLabel) are removed, because a connected session is now the only Ask AI option (#1685).

Additional Changes

• Clear message when the OpenCode CLI is missing. Choosing the OpenCode provider without opencode on your PATH showed a raw ENOENT error. It now says the CLI is missing and suggests installing OpenCode or picking another provider (#1669, closing #1503, by @Aayushyaash).
• One-line error when the remote port is taken. In remote mode Plannotator uses one fixed port, so a second session at the same time crashed with a stack trace. It now prints one line naming the port and suggesting PLANNOTATOR_PORT, and exits with the usual startup-failure code (#1692).
• Ask AI loads faster. Plannotator no longer asks the pi CLI for its models at startup, which could hold up Ask AI for up to 10 seconds. Pi's model list now loads when you pick Pi or start a Pi session, like Codex and OpenCode (#1692).
• Closing the tab stops a Pi answer. The Pi server kept an Ask AI answer running after you closed the tab or asked a new question. It now stops it, as the server used by Claude Code and OpenCode already did (#1668).
• Docs. The Claude Code, OpenCode, Pi, and AI features guides cover the mod, Ask this session, the opt-out, and the corrected plugin update steps, and troubleshooting has a new entry for "Claude Code still waits for my review" (#1691).

Known issues

• Leaving plan mode during a review. Under the Claude Code mod, Claude is not blocked while a plan review is open. Plan mode stays on and Claude is told the plan is not approved, but if you leave plan mode yourself (Shift+Tab) and keep talking, Claude can start editing before you approve.
• Review servers outlive Claude Code. A review the mod started keeps running after Claude Code exits, so it can be reattached with --continue or --resume. If you never resume that session, the server runs until you decide or close the tab.
• One session at a time in remote mode. Remote mode uses one fixed port, so two sessions cannot run at once. The second one now stops with a clear message; set PLANNOTATOR_PORT to run it on another port.

Install / Update

macOS / Linux:

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

Windows:

irm https://plannotator.ai/install.ps1 | iex

Claude Code Plugin: The plugin and the plannotator binary update separately, so run the install script above as well. In a terminal:

claude plugin marketplace update plannotator
claude plugin update plannotator@plannotator

Then restart Claude Code. Inside Claude Code, run /plugin marketplace update plannotator, then open /plugin → Installed → plannotator → Update now.

Pi:

pi update --extensions

OpenCode: Re-run the install script above. It now also clears the OpenCode 2 plugin cache.

What's Changed

• feat(questions): Decision flag, findQuestionBlocks, host footer slot by @backnotprop in #1664
• fix(hook): review Claude's plan file, not its stale inline snapshot by @workflow in #1667
• feat(ai): Ask this session (core + Pi) by @backnotprop in #1668
• fix(ai): show friendly error when opencode CLI is unavailable by @Aayushyaash in #1669
• feat(pi): non-blocking plan review, with Ask this session during review by @backnotprop in #1670
• feat(ai): Ask this session for OpenCode 2 (host-neutral pull bridge) by @backnotprop in #1671
• feat(claude-code): mod for non-blocking plan review, annotate, review and last, with Ask this session by @backnotprop in #1672
• feat(claude-code): plannotator tool for agent-initiated opens under the mod by @backnotprop in #1673
• docs(questions): suggest context and images in question blocks by @backnotprop in #1674
• chore(npm): Apache-2.0 license for @plannotator/ui and @plannotator/core by @backnotprop in #1675
• feat(annotate): open local image links in an HTML page in the image lightbox by @backnotprop in #1676
• fix(ui): srcdoc frame height with collapsed margins + fenceTheme host seam by @backnotprop in #1677
• feat(ui): embeddable read-only DiffFileTree shared with the code-review tree by @backnotprop in #1678
• chore: bump @plannotator/core 0.25.10 and @plannotator/ui 0.50.0 by @backnotprop in #1682
• fix(ui): pinpoint in a question card targets what was clicked, not the prompt by @backnotprop in #1683
• fix(claude-mod): restore the message picker for /plannotator-last by @backnotprop in #1684
• fix(ai): Ask AI uses only the session when a session bridge is present by @backnotprop in #1685
• feat(claude-mod): turn the Claude Code mod on by default by @backnotprop in #1686
• docs(skill): always use the plannotator tool over the CLI when you have it by @backnotprop in #1687
• feat(claude-mod): agent-run plannotator commands open through the mod, so Ask AI reaches the session by @backnotprop in #1688
• fix(install): stop stripping the Claude Code mod from the marketplace clone; clear OpenCode 2's plugin cache by @backnotprop in #1689
• feat(ui): first-run announcement for Ask this session and non-blocking reviews by @backnotprop in #1690
• docs: 0.28.0 — Claude Code mod on by default, Ask this session, correct plugin update steps by @backnotprop in #1691
• fix: 0.28.0 QA fixes — strict gates under the mod, clean port-in-use error, deferred pi discovery, Windows PATH by @backnotprop in #1692

New Contributors

• @workflow made their first contribution in #1667

Contributors

@workflow found why Claude Code plan review sometimes showed the plan that had just been denied. The write-up traced it to Claude Code capturing the plan before a same-message edit ran, with timings from a real session, and the PR came with tests and an end-to-end replay of the real hook event. First contribution to the project.

@Aayushyaash replaced the raw ENOENT error with a clear message when the OpenCode CLI is missing, a second contribution after the Ask AI dropdown fix in v0.27.25.

Community

• @modelpath-dev pinpointed where the missing-CLI error should be caught in #1503

Full Changelog: v0.27.25...v0.28.0