feat(gemini): add Gemini CLI plan review integration

* 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.

Author: backnotprop

README.md

@@ -4,7 +4,7 @@
 
 # Plannotator
 
-Interactive Plan & Code Review for AI Coding Agents. Mark up and refine your plans or code diffs using a visual UI, share for team collaboration, and seamlessly integrate with **Claude Code**, **OpenCode**, **Pi**, and **Codex**.
+Interactive Plan & Code Review for AI Coding Agents. Mark up and refine your plans or code diffs using a visual UI, share for team collaboration, and seamlessly integrate with **Claude Code**, **Copilot CLI**, **Gemini CLI**, **OpenCode**, **Pi**, and **Codex**.
 
 **Plan Mode Demos:**
 <table>
@@ -54,6 +54,7 @@ Plannotator lets you privately share plans, annotations, and feedback with colle
 
 - [Claude Code](#install-for-claude-code)
 - [Copilot CLI](#install-for-copilot-cli)
+- [Gemini CLI](#install-for-gemini-cli)
 - [OpenCode](#install-for-opencode)
 - [Pi](#install-for-pi)
 - [Codex](#install-for-codex)
@@ -116,6 +117,39 @@ See [apps/copilot/README.md](apps/copilot/README.md) for details.
 
 ---
 
+## Install for Gemini CLI
+
+**Install the `plannotator` command:**
+
+**macOS / Linux / WSL:**
+
+```bash
+curl -fsSL https://plannotator.ai/install.sh | bash
+```
+
+**Windows PowerShell:**
+
+```powershell
+irm https://plannotator.ai/install.ps1 | iex
+```
+
+The installer auto-detects Gemini CLI (checks for `~/.gemini`) and configures the plan review hook and policy. It also installs `/plannotator-review` and `/plannotator-annotate` slash commands.
+
+**Then in Gemini CLI:**
+
+```
+/plan                              # Enter plan mode — plans open in your browser
+/plannotator-review                # Code review for current changes
+/plannotator-review <pr-url>       # Review a GitHub pull request
+/plannotator-annotate <file.md>    # Annotate a markdown file
+```
+
+Requires Gemini CLI 0.36.0 or later.
+
+See [apps/gemini/README.md](apps/gemini/README.md) for details.
+
+---
+
 ## Install for OpenCode
 
 Add to your `opencode.json`:

apps/gemini/README.md

@@ -0,0 +1,89 @@
+# Plannotator for Gemini CLI
+
+Interactive plan review, code review, and markdown annotation for Google Gemini CLI.
+
+## Install
+
+**Install the `plannotator` command:**
+
+**macOS / Linux / WSL:**
+
+```bash
+curl -fsSL https://plannotator.ai/install.sh | bash
+```
+
+**Windows PowerShell:**
+
+```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:
+
+1. The agent creates a plan and calls `exit_plan_mode`
+2. The user policy auto-allows `exit_plan_mode` (skipping the TUI dialog)
+3. The `BeforeTool` hook intercepts the call, reads the plan from disk, and opens the Plannotator review UI in your browser
+4. You review the plan, optionally add annotations
+5. **Approve** → the plan is accepted and the agent proceeds
+6. **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:
+
+```json
+{
+  "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
+- `plannotator` binary on PATH
+
+## Links
+
+- [Website](https://plannotator.ai)
+- [GitHub](https://github.com/backnotprop/plannotator)
+- [Docs](https://plannotator.ai/docs/getting-started/installation/)

apps/gemini/commands/plannotator-annotate.toml

@@ -0,0 +1,10 @@
+description = "Open interactive annotation UI for a markdown file or folder"
+prompt = """
+## Markdown Annotations
+
+!{plannotator annotate {{args}}}
+
+## Your task
+
+Address the annotation feedback above. The user has reviewed the markdown file and provided specific annotations and comments.
+"""

apps/gemini/commands/plannotator-review.toml

@@ -0,0 +1,10 @@
+description = "Open interactive code review for current changes or a PR URL"
+prompt = """
+## Code Review Feedback
+
+!{plannotator review {{args}}}
+
+## Your task
+
+If the review above contains feedback or annotations, address them. If no changes were requested, acknowledge and continue.
+"""

apps/gemini/hooks/plannotator.toml

@@ -0,0 +1,8 @@
+# Plannotator policy for Gemini CLI
+# Allows exit_plan_mode without TUI confirmation so the browser UI is the sole gate.
+# Installed to: ~/.gemini/policies/plannotator.toml
+
+[[rule]]
+toolName = "exit_plan_mode"
+decision = "allow"
+priority = 100

apps/gemini/hooks/settings-snippet.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "BeforeTool": [
+      {
+        "matcher": "exit_plan_mode",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "plannotator",
+            "timeout": 345600
+          }
+        ]
+      }
+    ]
+  }
+}

apps/hook/server/index.ts

@@ -749,12 +749,30 @@ if (args[0] === "sessions") {
 
   let planContent = "";
   let permissionMode = "default";
+  let isGemini = false;
+  let planFilename = "";
+  let event: Record<string, any>;
   try {
-    const event = JSON.parse(eventJson);
-    planContent = event.tool_input?.plan || "";
+    event = JSON.parse(eventJson);
+
+    // Detect harness: Gemini sends plan_filename (file on disk), Claude Code sends plan (inline)
+    planFilename = event.tool_input?.plan_filename || event.tool_input?.plan_path || "";
+    isGemini = !!planFilename;
+
+    if (isGemini) {
+      // Reconstruct full plan path from transcript_path and session_id:
+      // transcript_path = <projectTempDir>/chats/session-...json
+      // plan lives at   = <projectTempDir>/<session_id>/plans/<plan_filename>
+      const projectTempDir = path.dirname(path.dirname(event.transcript_path));
+      const planFilePath = path.join(projectTempDir, event.session_id, "plans", planFilename);
+      planContent = await Bun.file(planFilePath).text();
+    } else {
+      planContent = event.tool_input?.plan || "";
+    }
+
     permissionMode = event.permission_mode || "default";
-  } catch {
-    console.error("Failed to parse hook event from stdin");
+  } catch (e: any) {
+    console.error(`Failed to parse hook event from stdin: ${e?.message || e}`);
     process.exit(1);
   }
 
@@ -768,7 +786,7 @@ if (args[0] === "sessions") {
   // Start the plan review server
   const server = await startPlannotatorServer({
     plan: planContent,
-    origin: detectedOrigin,
+    origin: isGemini ? "gemini-cli" : detectedOrigin,
     permissionMode,
     sharingEnabled,
     shareBaseUrl,
@@ -802,41 +820,56 @@ if (args[0] === "sessions") {
   // Cleanup
   server.stop();
 
-  // Output JSON for PermissionRequest hook decision control
-  if (result.approved) {
-    // Build updatedPermissions to preserve the current permission mode
-    const updatedPermissions = [];
-    if (result.permissionMode) {
-      updatedPermissions.push({
-        type: "setMode",
-        mode: result.permissionMode,
-        destination: "session",
-      });
+  // Output decision in the appropriate format for the harness
+  if (isGemini) {
+    if (result.approved) {
+      console.log(result.feedback ? JSON.stringify({ systemMessage: result.feedback }) : "{}");
+    } else {
+      console.log(
+        JSON.stringify({
+          decision: "deny",
+          reason: planDenyFeedback(result.feedback || "", "exit_plan_mode", {
+            planFilePath: planFilename,
+          }),
+        })
+      );
     }
+  } else {
+    // Claude Code: PermissionRequest hook decision
+    if (result.approved) {
+      const updatedPermissions = [];
+      if (result.permissionMode) {
+        updatedPermissions.push({
+          type: "setMode",
+          mode: result.permissionMode,
+          destination: "session",
+        });
+      }
 
-    console.log(
-      JSON.stringify({
-        hookSpecificOutput: {
-          hookEventName: "PermissionRequest",
-          decision: {
-            behavior: "allow",
-            ...(updatedPermissions.length > 0 && { updatedPermissions }),
+      console.log(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: "PermissionRequest",
+            decision: {
+              behavior: "allow",
+              ...(updatedPermissions.length > 0 && { updatedPermissions }),
+            },
           },
-        },
-      })
-    );
-  } else {
-    console.log(
-      JSON.stringify({
-        hookSpecificOutput: {
-          hookEventName: "PermissionRequest",
-          decision: {
-            behavior: "deny",
-            message: planDenyFeedback(result.feedback || "", "ExitPlanMode"),
+        })
+      );
+    } else {
+      console.log(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: "PermissionRequest",
+            decision: {
+              behavior: "deny",
+              message: planDenyFeedback(result.feedback || "", "ExitPlanMode"),
+            },
           },
-        },
-      })
-    );
+        })
+      );
+    }
   }
 
   process.exit(0);

apps/marketing/public/assets/icon-gemini.png

@@ -62,6 +62,15 @@ import AnnoReplace from './AnnoReplace.astro';
           <img src="/assets/icon-copilot.svg" alt="" class="w-4 h-4 icon-copilot" />
           <span>Copilot</span>
         </button>
+        <button
+          class="agent-btn"
+          data-agent="gemini"
+          data-command="curl -fsSL https://plannotator.ai/install.sh | bash"
+          data-video=""
+        >
+          <img src="/assets/icon-gemini.png" alt="" class="w-4 h-4" />
+          <span>Gemini</span>
+        </button>
         <button
           class="agent-btn"
           data-agent="opencode"
@@ -214,6 +223,14 @@ import AnnoReplace from './AnnoReplace.astro';
         ],
         detail: 'Then run in Copilot CLI:'
       },
+      gemini: {
+        steps: [
+          '/plannotator-review',
+          '/plannotator-annotate <file.md>',
+          'Use /plan for plan review with browser approval'
+        ],
+        detail: 'Then use in Gemini CLI:'
+      },
       pi: {
         detail: 'Or try without installing: pi -e npm:@plannotator/pi-extension'
       },