Plannotator Files

Follow @plannotator on X for updates

---

Missed recent releases?

| Release | Highlights | | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [v0.16.7](https://github.com/backnotprop/plannotator/releases/tag/v0.16.7) | Gemini CLI plan review, install script skills directory fix | | [v0.16.6](https://github.com/backnotprop/plannotator/releases/tag/v0.16.6) | Perforce support, Pi shared event API, suggested code prefill, file tree expand fix | | [v0.16.5](https://github.com/backnotprop/plannotator/releases/tag/v0.16.5) | Resize handle scrollbar fix, VS Code Marketplace publish | | [v0.16.4](https://github.com/backnotprop/plannotator/releases/tag/v0.16.4) | Compound planning improvement hook, GitHub Enterprise + self-hosted GitLab, dockview workspace, new themes | | [v0.16.3](https://github.com/backnotprop/plannotator/releases/tag/v0.16.3) | Pi phase configuration, CLI help, untracked file discovery fix, review scroll reset | | [v0.16.2](https://github.com/backnotprop/plannotator/releases/tag/v0.16.2) | Draggable comment popovers, cross-file annotation visibility, custom diff fonts, OpenCode verbose log fix | | [v0.16.1](https://github.com/backnotprop/plannotator/releases/tag/v0.16.1) | SSE stream idle timeout fix for external annotations API | | [v0.16.0](https://github.com/backnotprop/plannotator/releases/tag/v0.16.0) | GitHub Copilot CLI, external annotations API, bot callback URLs, interactive checkboxes, print support, diff display options | | [v0.15.5](https://github.com/backnotprop/plannotator/releases/tag/v0.15.5) | Custom display names, GitHub viewed file sync, expand/collapse all in file tree, search performance, WSL fix | | [v0.15.2](https://github.com/backnotprop/plannotator/releases/tag/v0.15.2) | Compound Planning skill, folder annotation, `/plannotator-archive` slash command, skill installation via platform installers | | [v0.15.0](https://github.com/backnotprop/plannotator/releases/tag/v0.15.0) | Live AI chat in code review, plan archive browser, folder file viewer, resizable split pane, Pi full feature parity | | [v0.14.5](https://github.com/backnotprop/plannotator/releases/tag/v0.14.5) | GitLab merge request review, login page image fix, Windows install path fix |

---

What's New in v0.17.0

v0.17.0 introduces AI-powered code review agents, token-level annotation in diffs, and merge-base diffs for PR-accurate comparisons. Three of the six PRs in this release came from external contributors, one of them a first-timer.

AI Code Review Agents

Codex and Claude Code can now run as background review agents directly from the Plannotator code review UI. Select an agent, launch it, and watch live log output stream into a detail panel while the agent works. When it finishes, its findings appear as external annotations in the diff viewer, tagged by severity.

Codex agents use their built-in codex-review command and produce priority-level findings (P0 through P3). Claude agents use a custom multi-agent prompt covering bug detection, security, code quality, and guideline compliance, with each finding classified as important, nit, or pre-existing. Both agents' findings include reasoning traces that explain the logic behind each annotation.

For PR reviews, the server automatically creates a local worktree so agents have full file access without affecting your working directory. Same-repo PRs use git worktree; cross-repo forks use a shallow clone with tracking refs for both branches. Pass --no-local to skip the worktree if you don't need file access.

The Pi extension has full agent review parity: stdin/stdout/stderr handling, live log streaming, result ingestion, and vendored review modules with import rewriting.

• #491

Token-Level Code Selection

The diff viewer now supports clicking individual syntax tokens to annotate them. Hover a token to see it underlined; click to open the annotation toolbar with the token's text and position as context (e.g., "Line 47: processOrder"). Token metadata is stored on the annotation and surfaced in sidebar badges and exported feedback.

Gutter-based line selection continues to work independently. The two selection modes don't interfere with each other.

• #500

Merge-Base Diffs

A new "Current PR Diff" option in the diff type selector uses git merge-base to find the common ancestor between your branch and the default branch, then diffs from that point. This produces the same diff you'd see on a GitHub pull request page. The existing "vs main" option (git diff main..HEAD) is still available but includes upstream changes that arrived after you branched, which can be noisy.

• #485 by @yonihorn

Additional Changes

• @ file reference support in annotate. OpenCode-style @file.md references now resolve correctly in /plannotator-annotate. The resolver strips the leading @ as a fallback when the literal filename doesn't exist, while still preferring real files named @something.md if present (#488 by @Exloz)
• Markdown hard line breaks and list continuations. Two-trailing-space and backslash hard breaks now render as <br> elements. Indented continuation lines after list items merge into the preceding bullet instead of becoming orphan paragraphs (#483, closing #482)
• Explicit local mode override. Setting PLANNOTATOR_REMOTE=0 or false now forces local mode, bypassing SSH auto-detection. Previously only 1/true had explicit meaning (#481 by @foxytanuki, closing #480)
• PR file content merge-base fix. File contents for expandable diff context are now fetched at the merge-base commit instead of the base branch tip. When the base branch has moved since the PR was created, the old file contents didn't match the diff hunks, causing crashes in the diff renderer. The fix fetches the merge-base SHA via GitHub's compare API and falls back gracefully if unavailable

---

Install / Update

macOS / Linux:

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

Windows:

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

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

Copilot CLI:

/plugin marketplace add backnotprop/plannotator
/plugin install plannotator-copilot@plannotator

Gemini CLI: The install script auto-detects ~/.gemini and configures hooks, policy, and slash commands. See apps/gemini/README.md for manual setup.

OpenCode: Clear cache and restart:

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

Then in opencode.json:

:::json
{
  "plugin": ["@plannotator/opencode@latest"]
}

Pi: Install or update the extension:

:::bash
pi install npm:@plannotator/pi-extension

VS Code Extension: Install from the VS Code Marketplace. Tested with Claude Code running in VS Code's integrated terminal. Not currently compatible with Anthropic's official VS Code extension due to upstream hook bugs.

---

What's Changed

• feat(review): token-level code selection for annotations by @backnotprop in #500
• feat(review): AI review agents, local worktree, and UI polish by @backnotprop in #491
• fix(annotate): support @ markdown file references by @Exloz in #488
• feat(review): add merge-base diff option for PR-style diffs by @yonihorn in #485
• fix: handle markdown hard line breaks and list continuations by @backnotprop in #483
• fix(remote): support explicit local override by @foxytanuki in #481
• fix(review): use merge-base SHA for PR file contents by @backnotprop

New Contributors

• @Exloz made their first contribution in #488

Contributors

@Exloz contributed the @ file reference fix for OpenCode's annotate mode (#488), including comprehensive test coverage for edge cases like real @-prefixed filenames and quoted input. First contribution.

@yonihorn returned with the merge-base diff option (#485), giving PR reviews the same diff semantics GitHub uses.

@foxytanuki continued contributing with the explicit local mode override (#481), their third PR after the CLI help message and SSE timeout fix.

Community members who reported issues addressed in this release:

• @rcdailey: #482 (markdown hard line breaks not rendering)
• @foxytanuki: #480 (PLANNOTATOR_REMOTE=false semantics)

Full Changelog: https://github.com/backnotprop/plannotator/compare/v0.16.7...v0.17.0