mirror of https://github.com/backnotprop/plannotator.git synced 2026-09-14 14:17:26 +08:00

Files

T

History

Michael Ramos 9130d2d6a3 feat(review): open a review on a specific base and diff type (#1484 )

Adds two session-only flags to plannotator review, parsed in the shared
parser so every host inherits them together:

- --base <ref> opens the session against a caller-chosen compare target
  (branch, origin/<branch>, tag, SHA, HEAD~N), probed with git rev-parse
  --verify --end-of-options before the server starts so a typo'd ref is a
  startup error with near-match suggestions instead of a silently
  mislabelled merge-base->HEAD diff.
- --diff-type <id> opens the session in one of the nine flat git diff
  modes (REVIEW_OPEN_DIFF_TYPES, pinned against GIT_DIFF_TYPES).

The flags are a seed, never a setting: nothing writes config.json or any
review cookie, and the UI stays fully mutable. Validation is pure in
packages/shared/review-open-state.ts (provider matrix errors on
jj/GitButler/P4/workspace/PR mode, promote-with-notice when the saved
default is base-irrelevant, fatal explicit contradiction).

A flagged base rides explicitBase semantics: the new initialBaseExplicit
server option (both runtimes) seeds baseExplicitlyChosen, suppressing the
startup origin/* upgrade and canonicalization, and openStatePinned rides
/api/diff so the client neither offers the first-run setup dialog (its
one-time cookie is NOT consumed) nor runs the panel-pair self-heal for a
pinned session. The since-base dropdown label now renders from the live
active base, matching the adjacent base picker.

Coverage: Bun CLI, opencode-review bridge, OpenCode embedded plugin, and
the Pi extension (re-vendored; strict validation on the slash-command
path only, programmatic callers unchanged). Skills, command stubs, help
text, and docs updated across every host surface.

2026-09-09 21:35:05 -07:00

commands

feat(review): open a review on a specific base and diff type (#1484 )

2026-09-09 21:35:05 -07:00

hooks

feat(gemini): add Gemini CLI plan review integration

2026-04-02 15:24:10 -07:00

README.md

Add an option to disable AI features (#1129 )

2026-07-26 09:59:15 -07:00

README.md

Plannotator for Gemini CLI

Interactive plan review, code review, and markdown annotation for Google Gemini CLI.

Install

Install the plannotator command:

macOS / Linux / WSL:

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

Windows PowerShell:

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

The installer auto-detects Gemini CLI (checks for ~/.gemini) and configures:

Policy file at ~/.gemini/policies/plannotator.toml — allows exit_plan_mode without the TUI confirmation dialog
Hook in ~/.gemini/settings.json — intercepts exit_plan_mode and opens the browser review UI
Slash commands at ~/.gemini/commands/ — /plannotator-review and /plannotator-annotate

How It Works

Plan Mode Integration

When you use /plan in Gemini CLI:

The agent creates a plan and calls exit_plan_mode
The user policy auto-allows exit_plan_mode (skipping the TUI dialog)
The BeforeTool hook intercepts the call, reads the plan from disk, and opens the Plannotator review UI in your browser
You review the plan, optionally add annotations
Approve → the plan is accepted and the agent proceeds
Deny → the agent receives your feedback and revises the plan

Available Commands

Command	Description
`/plannotator-review`	Open interactive code review for current changes or a PR URL
`/plannotator-review <pr-url>`	Review a GitHub pull request
`/plannotator-annotate <file>`	Open interactive annotation UI for a markdown file

Manual Setup

If the installer didn't auto-configure your settings (e.g. ~/.gemini/settings.json already existed), add the hook manually:

{
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "exit_plan_mode",
        "hooks": [
          {
            "type": "command",
            "command": "plannotator",
            "timeout": 345600
          }
        ]
      }
    ]
  }
}

Environment Variables

Variable	Description
`PLANNOTATOR_REMOTE`	Set to `1` for remote mode (devcontainer, SSH). Uses fixed port and skips browser open.
`PLANNOTATOR_PORT`	Fixed port to use. Default: random locally, `19432` for remote sessions.
`PLANNOTATOR_BROWSER`	Custom browser to open. macOS: app name or path. Linux/Windows: executable path.
`PLANNOTATOR_AI`	Set to `disabled` to disable Ask AI, Review Agents, and Guided Review.
`PLANNOTATOR_SHARE`	Set to `disabled` to turn off URL sharing.

Requirements

Gemini CLI 0.36.0 or later
plannotator binary on PATH

README.md

Plannotator for Gemini CLI

Install

How It Works

Plan Mode Integration

Available Commands

Manual Setup

Environment Variables

Requirements

Links