galaxy/specs/APP-4067/PRODUCT.md

Product Spec: Gemini CLI Plugin Install & Update Flow

Linear: APP-4067 Figma: none provided

Summary

Add install and update chip support for the Gemini CLI Warp plugin (gemini-warp), matching the existing Claude Code chip UX. Enable the listener so Warp processes structured notifications from Gemini sessions (session status, permission requests, task completion).

Problem

The gemini-warp extension already exists and uses the same structured OSC 777 notification protocol as Claude Code (warp://cli-agent title, JSON body with agent: "gemini"). However, Warp currently ignores these notifications because:

1. create_handler in the listener returns None for CLIAgent::Gemini.
2. plugin_manager_for returns None for CLIAgent::Gemini — there's no install/update chip.
3. There is no GeminiNotifications feature flag to gate the rollout.

Goals

• Gemini users see install/update chips that prompt them to set up the plugin.
• Clicking the chip auto-installs or auto-updates the plugin (Gemini CLI has first-class extension management commands).
• A manual instructions fallback is available for cases where auto-install fails.
• Structured notifications from the Gemini plugin are received and displayed (session status, blocked/success states, permission requests).

Non-Goals

• Changing the gemini-warp plugin itself (it's maintained separately in warpdotdev/gemini-cli-warp).
• Platform plugin / Oz harness support for Gemini (future work).

How Gemini CLI Extensions Work

Gemini CLI has a first-class extension system:

• Install: gemini extensions install <github-url-or-local-path> — copies the extension into ~/.gemini/extensions/<name>/.
• Update: gemini extensions update <name> — pulls the latest version from the source.
• Uninstall: gemini extensions uninstall <name>.
• Manifest: Each extension has a gemini-extension.json with name, version, description, and hook/MCP/command definitions.
• Hooks: Defined in hooks/hooks.json within the extension directory (not in the manifest). The gemini-warp plugin uses SessionStart, AfterAgent, Notification, BeforeAgent, and AfterTool hooks.

Key difference from Claude Code: Gemini extensions install from a GitHub URL directly (no separate marketplace add step). The install and update are each a single CLI command.

Key difference from OpenCode: Gemini CLI does have CLI commands for extension management, so auto-install and auto-update are viable.

User Experience

Install Chip

When a user starts a Gemini session and the plugin has never connected (no listener, no plugin_version reported):

• A green chip appears: "Notifications setup instructions"
• Clicking triggers auto-install via gemini extensions install https://github.com/warpdotdev/gemini-cli-warp --consent.
  • --consent skips the interactive confirmation prompt that would block the non-interactive shell execution.
• On success, a toast confirms installation and tells the user to restart Gemini.
• On failure, a toast appears with an error, and the user can click the info (ⓘ) button to open manual instructions in a split pane.

Manual install instructions (split pane):

• Title: "Install Warp Plugin for Gemini CLI"
• Subtitle: "Run the following command, then restart Gemini CLI."
• Steps:
  1. "Install the Warp extension" — command: gemini extensions install https://github.com/warpdotdev/gemini-cli-warp --consent
• Post-install notes: "Restart Gemini CLI to activate the plugin."

Update Chip

When the plugin is connected but reports a version below MINIMUM_PLUGIN_VERSION:

• Label: "Plugin update available"
• Clicking triggers auto-update via gemini extensions update gemini-warp.
  • The extension name is gemini-warp (the installed directory name under ~/.gemini/extensions/).
• On success, a toast confirms the update and tells the user to restart Gemini.
• On failure, a toast appears with an error, and the user can click the info (ⓘ) button to open manual instructions in a split pane.

Manual update instructions (split pane):

• Title: "Update Warp Plugin for Gemini CLI"
• Subtitle: "Run the following command, then restart Gemini CLI."
• Steps:
  1. "Update the Warp extension" — command: gemini extensions update gemini-warp
• Post-install notes: "Restart Gemini CLI to activate the update."

Version Detection

Two signals, matching the Claude Code pattern:

1. Filesystem check: ~/.gemini/extensions/gemini-warp/gemini-extension.json — read the version field to determine if the plugin is installed and whether it's outdated. Symlinks are followed (supports gemini extensions link).
2. Runtime signal: plugin_version field from the SessionStart event (emitted by on-session-start.sh in the plugin).

The filesystem check eliminates install chip flicker (the chip never appears if the plugin is already on disk) and enables update detection before the plugin connects.

Notification Listening

Once the plugin is installed, the Gemini session handler works identically to Claude Code / OpenCode: the DefaultSessionListener receives structured JSON events and forwards them to the sessions model. No special parsing is needed — the plugin already speaks the same protocol.

Chip Visibility Logic

Same as Claude Code:

1. Plugin connected, version >= minimum → no chip
2. Plugin connected, version < minimum → update chip
3. No listener, plugin installed on disk with version >= minimum → no chip (wait for connection)
4. No listener, plugin installed on disk with version < minimum → update chip
5. No listener, plugin not installed on disk → install chip (unless dismissed)
6. Chip dismissed → no chip (install and update have independent dismiss state)
7. Notifications disabled in settings → no chip

Dismiss Behavior

Same as Claude Code / OpenCode: install chip and update chip have independent dismiss state. The update chip tracks which minimum version was dismissed; a new minimum causes it to reappear.

Edge Cases

• Plugin installed via gemini extensions link (symlink): Filesystem check follows symlinks, so linked extensions are detected as installed. Version is read from the symlinked gemini-extension.json.
• gemini CLI not on PATH: Auto-install fails; user sees error toast and can use the manual instructions pane. The manual instructions pane commands will also need gemini on PATH, but the user can adapt (e.g. use full path or install Gemini CLI).
• Extension already installed: gemini extensions install may fail or warn. This is fine — the user already has the plugin.
• SSH sessions: Same experience as local. The gemini CLI must be available on the remote host. Filesystem checks don't apply to remote sessions (same as Claude Code).

Success Criteria

1. Starting a Gemini CLI session in Warp when the plugin is not installed shows a green install chip.
2. Clicking the install chip runs gemini extensions install and shows a success/failure toast.
3. After restart, the plugin connects, notifications appear in the inbox, and the chip disappears.
4. When the plugin reports a version below MINIMUM_PLUGIN_VERSION, an update chip appears.
5. Clicking the update chip runs gemini extensions update gemini-warp and shows a success/failure toast.
6. The info (ⓘ) button opens a split pane with manual instructions (not a modal).
7. Dismissing the chips works identically to other agents (independent dismiss state, version-tracked update dismiss).
8. Gemini notifications (stop, blocked, permission request) surface in the agent inbox when HOANotifications is enabled.
9. The install/update chip is gated behind both HOANotifications and GeminiNotifications feature flags. Notification listening only requires HOANotifications (consistent with other agents).

Validation

• Unit tests: GeminiPluginManager trait implementations (minimum version, can_auto_install, install/update instructions).
• Unit tests: is_installed() / needs_update() filesystem detection with temp directories.
• Unit tests: is_agent_supported returns true for CLIAgent::Gemini when feature flags are enabled.
• Unit tests: plugin_manager_for(CLIAgent::Gemini) returns Some(...) when flags are enabled.
• Manual testing: full install flow with a real Gemini CLI session.
• Manual testing: update flow — verify gemini extensions update pulls new version.
• Manual testing: notification flow — verify stop, blocked, permission request notifications appear.