backnotprop/plannotator v0.28.5

on GitHub

Follow @plannotator on X for updates

What's New in v0.28.5

Twelve PRs, one from a first-time contributor. Agents on Pi and OpenCode 2 can now open Plannotator reviews themselves without holding the session, a review can cover several files at once, and every decision now names the exact file it is about.

Several files in one review

plannotator annotate spec.md ui/mock.html notes.md now opens one review of all the files, in the order you typed them. A header switcher shows "2 of 3", the Files tab keeps that order, and one decision covers the whole set, with the feedback split into a section per file. Ask AI knows which file you are on, and your unsent comments are kept per file. The same works when an agent passes a list of files to the plannotator tool. If one of the paths does not exist, nothing opens and the error names the missing file. Words that are not file paths keep their old meaning, so annotate look at notes.md please still opens notes.md. (#1718)

The plannotator tool on Pi and OpenCode 2, off until you turn it on

On Claude Code (with the Plannotator mod) agents already had a plannotator tool. It is now on Pi and OpenCode 2 too. It matters when the agent opens Plannotator itself, for example when you ask it to "show me the HTML plan in Plannotator" or "open a Plannotator code review". Without the tool, the agent runs the plannotator command in its shell, which blocks the session until you finish and leaves Ask AI unable to reach the session. With the tool, the review opens right away while the agent keeps working, your decision comes back as a message, Ask this session works from that review, and the agent can list and close the reviews it opened.

The tool adds about 780 tokens to every request, so on Pi and OpenCode 2 it is off by default. The first Plannotator page you open there asks "Do you use Plannotator as a skill?" and turns it on for your next session if you say yes. You can change it any time with the new toggle in Settings → General (plan review, annotate and code review), the agentTool key in ~/.plannotator/config.json, or PLANNOTATOR_AGENT_TOOL. On Claude Code the tool stays on by default, since Claude loads it only when it is needed; the same switch turns it off there without turning off the rest of the mod. Your /plannotator-* commands work the same either way. (#1714, #1715, #1724, #1725)

The tool's description no longer includes the unfinished reply action, and Pi's bundled knowledge skill stays out of the model's context by default, keeping the promise from #842.

Every decision names the file it is about

A user reviewing two different files that were both named QUESTIONS.md approved one of them. The approval reached the agent as just "QUESTIONS.md — Approved." with no path, and the agent attached it to the other file. Every decision message now carries a Target: line with the full path (or URL, PR, or folder), taken from the review that recorded the decision, and reviews that share a file name are labelled with their folder, such as releases-2026-10-04/QUESTIONS.md. A code review decision names the PR that is on screen when you decide, even if you switched PRs inside the review.

A related gap is closed too: when a review's port was reused (a fixed PLANNOTATOR_PORT, remote mode, or rarely by chance), an old browser tab could submit a decision to the new review. Each review now has its own id, and a decision from a tab that belongs to a different review is refused with a "This review was replaced, reload" banner. plannotator sessions now lists each review's id and full path, and has a --json option. (#1729)

Ask this session reconnects after sleep

With the Claude Code mod, Ask AI in an open review could switch permanently to "This session is no longer available" after your computer slept or the network dropped for a few minutes. It now reconnects on its own, waiting a little longer between attempts while the review is unreachable. Running claude --continue while the old window is still open no longer makes the two windows fight over the review: the window you are using takes it over, each decision is delivered exactly once, and plan approvals reach the right window. If you quit Claude Code after a decision arrived but before Claude saw it, you get a notice next time saying where it was saved. (#1727)

Approve with a note in every gated review

Gated annotate reviews (--gate, or the tool with gate: true) opened from Claude Code never offered "Approve with a note…", even though the note could be delivered. They do now, for markdown and HTML alike, on every host that delivers the note with the approval. Your note reaches the agent as an "approved with notes" message. A plain approval is unchanged: plain output is still exactly The user approved. One thing for scripts: when you approve with a note, plain output now prints the approved-with-notes message instead of that line. Scripts should use --gate --json. (#1728)

Additional Changes

• Done says nothing was sent. Clicking Done with nothing to send showed "Feedback Sent". It now shows "Done, nothing was sent", and Close no longer claims a response was sent (#1730).
• Pi keeps the model you picked. Using /tree to re-answer something during plan execution switched the model back to the plan's original one. It now keeps your choice; moving into or out of plan mode still applies the phase's model (#1723, fixes #1722).
• Gruvbox diffs. Added lines in code review were grey on the Gruvbox theme. They are now Gruvbox green in light and dark (#1721).
• Safer settings. A web page in your browser can no longer change Plannotator's settings in the background, and saving settings from the VS Code panel works again, as do viewed-file progress and the Call Flow install there (#1724).
• Type checking now covers the Claude Code side's server code (#1720).

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(annotate): several files in one annotate review by @backnotprop in #1718
• feat(pi): the plannotator tool on Pi by @backnotprop in #1714
• feat(opencode): the plannotator tool on OpenCode 2 by @backnotprop in #1715
• feat(tool): agentTool switch with per-host defaults, Pi tool stability, drop the reserved reply action by @backnotprop in #1724
• feat(ui): agent tool switch in Settings and a one-time offer on Pi and OpenCode 2 by @backnotprop in #1725
• fix: decisions name their full target; refuse stale-tab decisions on a reused port by @backnotprop in #1729
• fix(mod): restart a dead Ask-this-session bridge; one watcher per launch across processes by @backnotprop in #1727
• fix(annotate): offer Approve with a note in every gated session that delivers it by @backnotprop in #1728
• fix(annotate): show a Done screen, not Feedback Sent, when Done sends nothing by @backnotprop in #1730
• fix(pi): keep the user's model on a /tree navigation within the same phase by @backnotprop in #1723
• Fix gruvbox positive diff colors by @TheEdgeOfRage in #1721
• fix(hook): type-check apps/hook/server and fix vibe-plan.ts narrowing by @backnotprop in #1720

New Contributors

• @TheEdgeOfRage made their first contribution in #1721

Contributors

@TheEdgeOfRage fixed the grey added lines in Gruvbox code review, with the color override the colorblind theme already uses.

Community:

• @jasonharrison reported the Pi model reset on /tree with a clear repro on Oh My Pi (#1722).

Full Changelog: v0.28.4...v0.28.5