backnotprop/plannotator v0.28.18

on GitHub

Follow @plannotator on X for updates

What's New in v0.28.18

Until now an agent only used the Inbox if you had connected it by hand and told it when the Inbox was the right place. This release does both for you: plannotator inbox connects the agents it finds on your computer, and each agent is told, in a line or a short note, to bring you decisions and finished work there while you are away. Code review gets rendered Markdown views, started by @leostera in his first contribution. The rest is Inbox reading and navigation, a Settings page in sections, and a handful of fixes. 25 PRs in all, one from a first-time contributor.

plannotator inbox connects your agents

When you run plannotator inbox (not --background, which is how agents start it), it now finds the agents on this computer that are not connected yet, connects them, and says so on the terminal:

Connected Codex, Gemini CLI and Cursor to the Inbox (Claude Code was already on).

Codex, Gemini CLI, Amp and Windsurf/Devin get their own mcp add. Cursor, Kiro and the Claude desktop app get one plannotator-inbox key in their JSON config, and every other byte of that file stays as it was. Pi and OpenCode with Plannotator's extension or plugin get the inbox tool switched on, and Claude Code already has it through the plugin. Each entry runs <your plannotator binary> inbox mcp, and the agent uses it from its next session.

A later run connects an agent you installed since, and names it once ("Connected Amp to the Inbox (new on this computer)"). An agent you turned off, or whose entry you removed, is never added back by itself, and an existing plannotator-inbox entry that runs something else is never replaced. PLANNOTATOR_INBOX_CONNECT=0 skips the step. plannotator uninstall removes only the entries it recorded adding, and gives each JSON file back exactly as it was; --dry-run lists them first.

• #1885

Agents are told when to use it

Connecting an agent is half of it. The tool descriptions explained how to use the Inbox but never said when, so agents rarely reached for it unprompted. Four changes cover that:

• The tool and MCP text now say when. The person may not be watching; a decision only they can make goes in a :::question, and the agent keeps working; finished long work goes with its files attached; ask in the chat when the person is there; never send routine progress. send_message no longer tells agents whose reply arrives by itself to call wait_for_reply. We checked the wording against scripted agent runs across nine scenarios, including the two where the Inbox is the wrong choice. (#1876)
• A one-line reminder at session start. Once you have run the Inbox, a session that has the inbox tool gets one fixed line: "Plannotator Inbox is on: when you finish long work, or need a decision the person isn't here to give, send it with plannotator_inbox send_message and keep going. Their reply comes back here." Claude Code and Pi get it once per session, OpenCode on each request. It never changes during a session, so it does not break the prompt cache. Turn it off with inboxReminder in ~/.plannotator/config.json. Claude Code also gets the plannotator_inbox tool before you have ever opened the Inbox: its first call starts the Inbox in the background, with no browser tab. (#1886)
• A note in each agent's instructions, with your yes. The first time you open the Inbox after it connected your agents, a card asks once whether to add a short marked section to each agent's own instructions file (~/.claude/rules/plannotator-inbox.md, Codex's AGENTS.md, GEMINI.md, Pi's instructions file, and OpenCode's AGENTS.md only when you already have one). It shows each file before writing. A note you edited is never overwritten, and removing a note gives the file back byte for byte. plannotator inbox --notes codex,gemini does the same from the terminal. (#1889)
• Settings → Agents. One group per agent found, with up to three switches: Reaches the Inbox, Reminder at session start, and Note in its instructions. A change applies to that agent's next session. Agents not found fold under "Not found on this computer", with the command or link to connect each by hand. (#1889)

The plannotator skill's Inbox section is now short and points agents at plannotator inbox --help for the details, which keeps the skill from drifting out of date (#1887). And an OpenCode 2 bug that shut down the Inbox reply wake's event subscription at setup is fixed: the wake leaned on a fallback, and where that fallback failed, a reply never reached an idle session (#1891).

• #1885, #1886, #1889, #1876, #1887, #1891

Rendered Markdown in code review

A Markdown file in a code review used to be readable only as a line diff. Each Markdown file now has a view menu in its header with three choices: Source (the line diff, as before), Changes (the rendered document with added, removed and changed sections marked, unchanged runs folded and source lines in a gutter) and Read (the whole new version rendered, with no diff marks). A view you pick becomes the starting view for every other Markdown file you have not set by hand, and is remembered for the next review. P steps the current file through the views.

Select text in a rendered view to comment on it. The comment is a file comment that carries the quoted text, so the agent sees exactly what you meant, and the export, the sidebar and a PR review all show the quote. Images load from the revision on screen. In a PR review, remote images wait behind "Load remote images", so opening someone else's Markdown does not tell a tracking pixel your address. Mermaid and Graphviz fences show as code here, which keeps the review page as light as it was.

@leostera wrote the first version, a Preview/Diff toggle for Markdown files, as his first contribution, and it grew into the menu above during review.

• #1879, by @leostera

Reading in the Inbox

• A new message in the thread you have open counts as seen. Before, a message that arrived while you were reading stayed bold and "new" even though it was right in front of you. It now counts as seen once its first lines have been on screen for a second, while the tab is visible, the window has focus and nothing covers the thread. At the end of the thread the view scrolls just far enough to show it; elsewhere, the "↓ N new" pill counts it. Screen readers hear "New message from ". (#1890)
• The row you open stays put. Opening a New row used to send it to the folded Quiet section a moment after the click, taking keyboard focus with it. While a thread is open, the list's rows no longer move. When you close the thread, the list settles into place with a short slide (none under reduced motion), and agent activity that arrived while you read waits behind "N new · Show". (#1875)
• A way back to the list with a file open. With a file open beside a thread, the list and sidebar are hidden, and the first control at the top left was Archive. The thread header now leads with ‹ Inbox (or the project's name), which closes the file and brings the list back with focus on the thread's row. The reply box's chips also wrap in that narrower column instead of spilling out. (#1871, #1881)
• Attachments in the message header. A message with files shows "📎 3 attachments · 1 changed" in its sender line. Click it to see the tiles right under the sender, without scrolling to the end of a long message. (#1869)

Inbox Settings, archived threads, and light or dark

• Settings in sections. Settings is now a page with General, Agents, Devices, Archived, Storage and About, each at its own address (#settings/agents). General holds the theme, notifications and the sound; Devices holds Over your tailnet; About holds the version and updates. The sidebar steps aside while Settings is open. Old #settings links still land. (#1883)
• Archived threads leave the list. They used to sit in Quiet with everything you had merely read. They now live in Settings → Archived, newest first, with Unarchive, which opens the thread back in the list. If an agent writes in an archived thread, the thread comes back to the list while something waits on you, you can answer without unarchiving it, and it goes back to Archived once handled. (#1874)
• Light and dark. A sun or moon button at the right end of the sidebar's Settings row flips the theme; Settings → General has Light, Dark and Match system. It is the same preference plan review, code review and annotate use, so a choice in one carries to the others. (#1878)
• The Decisions page's project switch shows counts. The plain dropdown is now a list that shows each project's folder and how many decisions are waiting and settled. (#1873)

Quotes render as one quote

A block quote with blank > lines, a code fence or a list inside it was split into one quote per line: the bar broke into segments, fences showed as literal backticks, and the code read as prose. A run of > lines is now one quote, with real code blocks, lists and nested quotes inside it. This applies to plan review, annotate and the Inbox.

Two changes you might notice. A line like #Title (no space after #) is no longer a heading, following CommonMark and GitHub, so #123 at the start of a line keeps its issue link. And in a plan diff, an edit anywhere inside a quote that holds a code fence shows the whole quote as changed.

• #1868

The plannotator tool is on by default in Oh My Pi

When our Pi extension runs inside Oh My Pi, the plannotator agent tool is now on by default. Oh My Pi lists an extension tool as one short line and loads its schema only when needed, so the tool costs about 50 tokens there, against about 780 on every request in plain Pi. Plain Pi and OpenCode 2 stay off by default. PLANNOTATOR_AGENT_TOOL and agentTool in config.json still override it either way.

• #1870, following #1814 from @tedtramonte

Additional changes

• Long question choices can be picked. A choice longer than 200 characters was refused in the Inbox ("is not one of the question's choices"), and in plan review the pick saved but never showed. Both work now, and answers saved by older builds show their pick again. (#1888)
• Stopped: no is not a stop. An agent that filled in Stopped: no, none or n/a put its thread in "Stopped on you". A bare negative word is now read as no stop, on Holds up: too. Threads already listed that way stay where they are. (#1877)
• Mark read fixes. The note Mark read sends the agent no longer counts as your reply, so news that arrives after a Mark read shows as New. Mark read on an archived thread that came back sends it to Archived as the toast says. Undo reopens only the questions that Mark read closed. These were found by a new model of the Inbox's thread states, checked against the store after every step. (#1882, #1884)
• The annotation toolstrip stays on top. In the Inbox's file view, scrolling put the document over the Select / Pinpoint / Markup toolstrip, and over the stepping bar's file list. (#1880)
• jj reads file paths literally. In a jj review, a file whose name contains |, ~ or quotes was read as a fileset expression, so the review could show another file's contents. (#1879)

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

• Inbox: attachments in the message header by @backnotprop in #1869
• Pi extension: the plannotator tool is on by default in Oh My Pi by @backnotprop in #1870
• Quotes: one quote per run of > lines, with code fences and lists inside by @backnotprop in #1868
• Inbox: a way back to the list while a file is open beside the thread by @backnotprop in #1871
• Inbox: tell agents when to use it (eval-backed instruction text) by @backnotprop in #1876
• Inbox: a project switch on the Decisions page that shows each project's counts by @backnotprop in #1873
• Inbox: light/dark toggle on the Settings row, and a Theme row in Settings by @backnotprop in #1878
• Inbox: archived threads leave the list for a Settings panel with Unarchive by @backnotprop in #1874
• Inbox: the reply box's skip chip wraps inside itself at any width by @backnotprop in #1881
• Inbox: a bare negative word on Stopped: or Holds up: is no stop by @backnotprop in #1877
• Inbox: keep the annotation toolstrip above the attached document by @backnotprop in #1880
• Inbox: the thread-state model, checked against the store, with trace fixtures by @backnotprop in #1882
• Inbox: the row you open stays put; the list settles when the thread closes by @backnotprop in #1875
• Inbox: fix the thread-state model's violations A, B and C by @backnotprop in #1884
• Questions: a choice longer than 200 characters can be picked by @backnotprop in #1888
• Inbox: Settings in sections by @backnotprop in #1883
• Skill: a short Inbox section that points at plannotator inbox --help by @backnotprop in #1887
• Inbox: a new message in the thread you have open counts as seen on sight by @backnotprop in #1890
• Review: add rendered Markdown previews by @leostera in #1879
• Inbox: plannotator inbox connects the agents on this computer by @backnotprop in #1885
• OpenCode 2 Inbox wake: keep the event subscription when the tool transform is lazy by @backnotprop in #1891
• Inbox: a one-line reminder at session start, and Claude Code's Inbox tool before the first run by @backnotprop in #1886
• Inbox: the note in each agent's instructions, the first-open card, Settings → Agents by @backnotprop in #1889
• Inbox: seen-on-sight DOM test no longer depends on wall-clock time by @backnotprop in #1892
• Inbox: a restart from an older Inbox never connects agents by @backnotprop in #1894

New Contributors

• @leostera made their first contribution in #1879

Contributors

@leostera built rendered Markdown previews for code review (#1879), his first contribution to the project. His Preview/Diff toggle, with the full document rendered through the shared Markdown renderer, is the base the Source / Changes / Read views grew from.

@tedtramonte reported in #1814 that Ask this session was missing in Oh My Pi and confirmed the fix. Making the plannotator tool default to on in Oh My Pi (#1870) is a follow-up to that report.

Full Changelog: v0.28.17...v0.28.18