mirror of
https://github.com/backnotprop/plannotator.git
synced 2026-09-14 14:17:26 +08:00
Michael Ramos
1800c24d80
* feat(gemini): add Gemini CLI plan review integration Adds a new `apps/gemini-hook/` adapter that enables Plannotator plan review for Gemini CLI users via the BeforeTool hook system. The adapter reads the plan file from disk (Gemini provides a path, not inline content), delegates to the shared @plannotator/server for the browser-based review UI, and translates the decision back into Gemini's hook output format. Requires an upstream fix (google-gemini/gemini-cli#21802) that makes `decision = "allow"` user policies work for exit_plan_mode, allowing hooks to replace the built-in TUI approval dialog. Includes: - apps/gemini-hook/server/index.ts — stdin/stdout adapter - apps/gemini-hook/hooks/ — policy TOML + settings snippet - scripts/install.sh — Gemini binary download, policy install, settings config For provenance purposes, this commit was AI assisted. * refactor(gemini): use single binary with auto-detection instead of separate app Removes apps/gemini-hook/ — the plannotator binary now auto-detects Gemini CLI from stdin (plan_path = file on disk) vs Claude Code (plan = inline content) and branches input parsing + output formatting. Config fixtures live in apps/gemini/ (policy TOML + settings snippet). Install script gates on ~/.gemini existing so Claude-only users are unaffected. For provenance purposes, this commit was AI assisted. * test(gemini): add manual sandbox script for Gemini CLI integration Three modes: - --simulate: pipes BeforeTool JSON to hook, tests approve/deny output - (default): runs local patched Gemini build - --nightly: installs Gemini nightly and runs it Backs up and restores ~/.gemini config on exit. For provenance purposes, this commit was AI assisted. * feat(gemini): add slash commands, marketing tab, and docs for Gemini CLI - Add /plannotator-review and /plannotator-annotate slash commands (.toml) - Install Gemini slash commands in all three install scripts (sh, ps1, cmd) - Add Gemini tab to marketing landing page with icon - Add Gemini CLI to top-level README install section - Create apps/gemini/README.md with full setup and usage docs - Remove stale dev:gemini script and regenerate bun.lock For provenance purposes, this commit was AI assisted. * fix(gemini): merge hook into existing settings.json instead of printing instructions When ~/.gemini/settings.json already exists, use node to JSON-merge the BeforeTool hook config rather than asking the user to do it manually. Falls back to instructions only if node is unavailable. For provenance purposes, this commit was AI assisted. * fix(gemini): handle plan_filename rename and fix scoping bug Gemini CLI nightly renamed plan_path to plan_filename in exit_plan_mode. Accept both field names for forward/backward compatibility. Reconstruct full plan path from transcript_path + session_id + plans/ + filename. Also hoist planFilename variable out of try block so it's accessible in the deny output path (was causing ReferenceError). For provenance purposes, this commit was AI assisted. * fix(gemini): dim approve button when annotations exist for Gemini CLI Gemini's hook runner ignores systemMessage on the allow path, so approve-with-feedback is silently dropped — same limitation as Claude Code. Extend the existing UI gate to also apply for gemini-cli origin. For provenance purposes, this commit was AI assisted. * fix(gemini): add AGENT_CONFIG entry and fix sandbox simulate mode Register "gemini-cli" in AGENT_CONFIG so the UI shows "Gemini CLI" with proper badge styling instead of generic "Coding Agent" fallback. Update sandbox simulate mode to match production input format: use plan_filename instead of plan_path, include transcript_path, and simulate the Gemini directory structure for path reconstruction. For provenance purposes, this commit was AI assisted.
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— allowsexit_plan_modewithout the TUI confirmation dialog - Hook in
~/.gemini/settings.json— interceptsexit_plan_modeand opens the browser review UI - Slash commands at
~/.gemini/commands/—/plannotator-reviewand/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
BeforeToolhook 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_SHARE |
Set to disabled to turn off URL sharing. |
Requirements
- Gemini CLI 0.36.0 or later
plannotatorbinary on PATH