backnotprop/plannotator v0.27.23

on GitHub

Follow @plannotator on X for updates

What's New in v0.27.23

This release brings Bitbucket Cloud to PR review, lets agents put questions in a plan that you answer in place, and adds an opt-in setting that keeps Plannotator up to date for you. Code review also remembers which files you have viewed, can be pointed at another repository or worktree, and several fixes land for Pi and keyboard users. It contains thirteen pull requests, three of them from community contributor @oorestisime.

Bitbucket Cloud pull requests

PR review used to recognize only GitHub and GitLab links. plannotator review https://bitbucket.org/<workspace>/<repo>/pull-requests/<id> now opens a Bitbucket Cloud pull request with the same review experience:

• the diff and a local checkout for full file access
• existing comments, with their code context
• image previews
• Guided Review and Code Tour

From the review you can post general and inline comments, approve, or request changes. Bitbucket has no command-line tool like gh, so Plannotator talks to its API directly with an Atlassian API token. Set PLANNOTATOR_BITBUCKET_EMAIL and PLANNOTATOR_BITBUCKET_TOKEN; the docs list the scopes the token needs.

Under the hood, PR mode now runs through one provider per platform. The screen shows only what that platform supports, which is why the PR Artifacts panel is absent on Bitbucket. GitHub and GitLab were moved onto the same seam and behave exactly as before. We checked this by recording every gh call against real stacked PRs on the old and new code and comparing them.

Not yet supported on Bitbucket:

• replying to or resolving existing threads
• syncing viewed files back to Bitbucket
• stacked PRs
• Bitbucket Data Center

(#1641, toward #1583 and #671, requested by @Toparvion and @bahayden)

Questions in plans, answered in place

An agent can now put questions in a plan or document as :::question blocks with checkbox choices and a Recommended: line. Plannotator draws each one as a card. You can:

• pick an answer, type your own under "Other…", add a note, or skip it
• take the agent's suggestion with Accept recommended

The header shows how many you have answered, and clicking that count jumps to the next open question. The sidebar lists them all.

Answers travel with your feedback in an "Answers to your questions" section at the top. If answering questions is all you did, the main button reads Send answers. The agent is then told you answered its questions and asked to revise the plan, rather than being told the plan was rejected. Answers are saved like any other annotation, so they survive a reload and can be undone. Question and option text stays selectable, so you can still comment on the wording.

The /plannotator skill teaches agents the syntax, including when not to ask. A document with no questions renders and exports exactly as before. If you already used :::question as an ordinary callout, it now renders as an answerable card. One limit to know: approving a plan in Claude Code passes no message to the agent, so answers given with Approve do not reach it. Plannotator warns you before that happens.

(#1637, #1638, #1639)

Opt-in automatic updates

The "new version available" notice tends to appear while you are busy with something else. You can now turn on Keep Plannotator up to date in Settings, with "autoUpdate": true in ~/.plannotator/config.json, or with PLANNOTATOR_AUTO_UPDATE=1.

With it on, Plannotator checks for a new release at most once a day, in the background, after a session has already started. It never slows down a hook or a command. When a newer version exists and no other review is open, it runs the normal install script for that exact version and writes the output to update.log. The next time you open Plannotator it tells you what version you are on now, or that the update failed and where the log is.

The installer now remembers the flags you installed with, such as --minimal or --skip-codex, so an automatic update installs the same way you did. The install scripts also replace the binary safely while it is running: on macOS and Linux the new file is renamed into place, and on Windows the running copy is moved aside first. Auto-update is off unless you turn it on, and it skips development builds, the OpenCode and Pi packages, and binaries in folders it cannot write to.

(#1636, closing #1634, requested by @drj613)

Code review remembers what you have viewed

Files you mark as viewed now stay viewed the next time you review the same branch, including after a restart or after sending feedback. A mark is tied to the exact contents of the file you saw, so a file that changed since then comes back unviewed. This works for local Git reviews and pull requests. Each mark is a small record in ~/.plannotator/review-progress/ that holds the file's path. Turn it off with PLANNOTATOR_REVIEW_PROGRESS=0 or { "reviewProgress": false }, and plannotator uninstall --purge removes it.

Viewed marks are now kept per diff type. Viewed marks stored in older drafts are ignored once, the first time you open a review after updating.

(#1632, closing #1136, by @oorestisime)

Review another repository or worktree

plannotator review ../other-repo and /plannotator-review ./worktrees/feature now review that directory without moving your agent session:

• A folder inside a repository reviews the whole repository.
• A folder that holds several repositories opens the combined workspace review.
• Everything after that follows the chosen directory: staging, drafts, viewed marks, Guided Review and the feedback label.

Extra words still work as before. /plannotator-review please check my changes, or even look at the api/users code, reviews the current repository and tells you which words it ignored. A mistyped path given on its own, such as ./backnd, stops with an error instead of quietly opening the wrong repository. A PR link anywhere in the words now opens that PR.

(#1644, closing #896 and #1482, by @oorestisime)

Additional Changes

• Keyboard scrolling works as soon as a review opens. Down, Page Down, Space, Home and End did nothing in plan review and annotate until you clicked the document. They now scroll it right away, without moving focus or interfering with shortcuts, dialogs, comment boxes or vim mode. Code review is a follow-up (#1648, closing #1647, reported by @henriquegeremia).
• No more Pi skill conflict warning. With both the install script and the Pi extension installed, Pi warned on every start that two plannotator skills collided. The extension now adds its copy only when no other one is loaded, so extension-only users still get the skill (#1643, closing #1642, reported by @tekumara).
• OpenCode plugin on stable packages. The plugin now builds against the published @opencode-ai/plugin for OpenCode 1 and @opencode/plugin for OpenCode 2, instead of a nightly build. The published plugin is unchanged in behavior (#1640, closing #1196, by @oorestisime).
• OpenCode 2 checked on every change. CI now installs a current OpenCode 2 and loads the packed plugin into it (#1631).
• Link widgets for hosts. @plannotator/ui re-exports the editor's link-widget API, so apps that embed Plannotator's editor can draw their own chips for links (#1633).

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.23 and restart Pi.

OpenCode: Clear cache and restart:

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

What's Changed

• ci(opencode): smoke the v2 plugin against a current OpenCode 2 by @backnotprop in #1631
• feat(review): persist viewed-file progress across review sessions by @oorestisime in #1632
• feat(ui): re-export linkWidgets for host link widgets by @backnotprop in #1633
• feat: opt-in background auto-update by @backnotprop in #1636
• feat(ui,core): in-document question blocks, core and ui by @backnotprop in #1637
• feat(editor): question answers, history, progress chip, Questions panel, Send answers by @backnotprop in #1638
• feat: question answers reach the agent by @backnotprop in #1639
• chore(opencode): migrate plugin dependencies to stable APIs by @oorestisime in #1640
• feat(review): Bitbucket Cloud PR review behind a PR provider seam by @backnotprop in #1641
• fix(pi): stop the plannotator skill colliding with the CLI install by @backnotprop in #1643
• feat(review): accept repository and worktree directory targets by @oorestisime in #1644
• fix(editor): scroll keys work on load without clicking the document by @backnotprop in #1648
• fix(review): path-shaped prose words no longer fail the review by @backnotprop in #1649

Contributors

@oorestisime contributed three of this release's pull requests. They built durable viewed-file progress for code review, moved the OpenCode plugin onto the stable OpenCode packages, and added directory targets to plannotator review, each with thorough tests and clear notes on the tradeoffs.

Community

• @drj613 asked for automatic updates in #1634, and @nclark added that they rarely update for exactly that reason
• @Toparvion explained how their team uses Plannotator with Bitbucket Cloud and Guided Review in #1583, and @bahayden first asked for other PR platforms in #671
• @dm3ch asked to review a specific worktree in #896, and @ben-reitz asked to pick a repository in a multi-repo workspace in #1482
• @tekumara reported the Pi skill conflict in #1642
• @henriquegeremia reported that keyboard scrolling needed a click first, with exact steps, in #1647
• @sergical opened #1196 to move the OpenCode 2 adapter to the stable plugin API
• @ashish921998 weighed in on keeping viewed state across review iterations in #1136

Full Changelog: v0.27.22...v0.27.23