backnotprop/plannotator v0.27.12

on GitHub

Follow @plannotator on X for updates

What's New in v0.27.12

The largest release of the 0.27 line: seven pull requests, two of them from community contributors, one a first-time contribution. The headline is a rebuilt decision header across every review surface, alongside a new hover card for code symbols and a set of community fixes. Every change went through independent adversarial review, and the release was gated by a 26-agent QA sweep before tagging.

One decision control across every surface

The header buttons for finishing a review grew organically over the years and ended up inconsistent: annotate showed different buttons than code review, approve sat next to send feedback where a stray click could pick the wrong one, and some finishing actions only existed as keyboard shortcuts. This release replaces all of it with a single adaptive control.

Every annotate surface and both code review destinations now show one primary action that reflects your session: Done (or Approve where approval is real) when there is nothing to send, Send Feedback with a count once there is. The alternate decisions live behind a caret: send with a note (the menu morphs into a composer in place), request changes with overall feedback, and an explicit discard path behind a single confirmation. Approve and send feedback never render side by side anywhere. Cmd+Enter always fires exactly what the visible primary says.

Approving with notes now actually works. Previously, notes attached to an approval were silently discarded by every runtime. Approvals that carry notes are delivered to your agent with clear framing that they are non-blocking guidance, not a change request. The capability is advertised by the server, so older components fail closed instead of dropping your words. The review sidebar also gains a "+ General comment" button for review-level comments that are not tied to a line, and the local feedback archive now records whether a comment was review-level or line-level.

A few behavior changes worth knowing: bare approvals no longer send the old "LGTM - no changes requested." placeholder text, approving despite open annotations is now an explicit two-step (caret, then confirm) instead of a dimmed one-click button, and pressing Escape on an open header menu closes just the menu instead of also triggering whatever Escape used to do underneath.

The design came directly from community feedback asking for overall review comments, an integrated global comment field, and a fast "that's fine" path for message annotation. #1458

Hover cards for code symbols

Rest your pointer on an identifier in a code review diff and Plannotator shows a card: the symbol's kind, a best-effort signature, its doc comment, where it is defined, and a sample of references, each linking into the References panel. Everything is powered by the same ripgrep search that backs Cmd+click, so there is nothing to install and nothing indexes your repo. If ripgrep is missing or the answer is weak, the card simply does not appear.

Because hover affordances are personal, the first review after updating shows a one-time introduction with a live try-it: hover the demo token inside the dialog and the real card opens against it. Choose your trigger right there: on hover (the default, matching the VS Code hover delay of 300ms), only while holding Cmd (Ctrl on Windows and Linux), or off. A delay setting offers faster and more relaxed dwell times. Everything lives in Settings under the Editor tab, and anyone who had turned the earlier experimental toggle off stays off without seeing the dialog.

The References panel also moved: Cmd+click and card links now open it beside the diff instead of splitting below it, so it stops stealing vertical room from the code you are reading. #1461, #1462, #1465

Compare your local branch with its remote

A new "Local vs remote branch" diff type answers the question "what would I push right now?": local commits the remote does not have, staged and unstaged edits, and untracked files, all compared against the branch's configured remote-tracking ref from your last fetch. It resolves the upstream properly rather than assuming an origin branch of the same name, only appears when the branch actually has an upstream, and shows a clear empty state when local and remote match. It never touches the network; fetching mid-review raises the existing refresh banner.

Contributed by @leoreisdias, whose implementation carried both server runtimes, the settings integration, and a genuinely thorough test suite including a real bare-remote integration test. #1451

OpenCode: the session URL notice can no longer burn a model turn

On recent OpenCode 2 betas, the "Plannotator session ready" notice posted into the transcript could wake a model turn on its own, burning tokens while the reviewer was still annotating, with the real feedback then queued behind that spurious turn. The notice is now sent with explicit queue delivery, the same mechanism feedback already uses, so it renders in the transcript and waits for a genuinely user-initiated turn no matter how the host behaves.

Reported by @Naasha with an unusually well-researched diagnosis that correctly identified the upstream mechanics, closing #1459. #1460

Additional Changes

• Skill fix for file approval: the installed agent skills now instruct agents to use --gate --json when a user asks to approve a saved plan or document, so an agent can no longer promise an Approve button that plain annotate does not render. Contributed by @zhangjinzan1 in their first contribution, complete with a freshness test that keeps the guidance from drifting. #1453
• Insecure-context fix: note and comment ids are minted through a fallback-safe generator, so remote-mode sessions served over plain http can no longer lose a typed note to a missing crypto.randomUUID.
• Escape discipline: header menus and popovers consume the Escape that dismisses them, and vim navigation defers to open popovers, so one keypress does one thing.

Install / Update

macOS / Linux:

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

Windows:

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

Claude Code Plugin: Run /plugin in Claude Code, find plannotator, and click "Update now".

Pi: Update @plannotator/pi-extension to 0.27.12 and restart Pi.

OpenCode: Clear cache and restart:

rm -rf ~/.bun/install/cache/@plannotator

What's Changed

• feat: unified decision control across annotate and code review in #1458
• feat(review): token hover cards, Tier 0 in #1461
• feat(review): hover card trigger settings and first-run introduction in #1462
• feat(review): compare local branch with remote by @leoreisdias in #1451
• fix(opencode): queue-deliver the session URL notice by report from @Naasha in #1460
• fix(review): open the References panel beside the diff in #1465
• docs(skills): require gate for file approval by @zhangjinzan1 in #1453

New Contributors

• @zhangjinzan1 made their first contribution in #1453

Community

@leoreisdias returned with the local-vs-remote diff mode, an implementation clean enough that our adversarial review's only required change was a regenerated build manifest, and they fixed the review's optional suggestions before we finished writing them up. @zhangjinzan1 caught a real footgun in the installed skills, diagnosed exactly why an agent following them would promise an approval it could not deliver, and shipped the fix with a drift-proof test in a first contribution that merged as written. @Naasha filed one of the best bug reports this project has received, tracing a token-burning notice on OpenCode 2 betas down to the exact upstream wake semantics.

The unified decision control itself is community-driven: it exists because users kept asking for overall review comments, an integrated global comment field, and a faster way to say "that's fine" - and because one of you told us you never wanted to see Approve sitting next to Send Feedback again.

Thank you. Plannotator gets better because you tell us where it falls short.

Full Changelog: v0.27.11...v0.27.12