118 lines
5.4 KiB
Markdown
118 lines
5.4 KiB
Markdown
# Product Spec: Plugin Installation Fallback Modal
|
|
|
|
## Problem
|
|
|
|
When the Warp notification plugin can't be auto-installed (SSH session, or a previous install attempt failed), the user currently has no way to learn how to install it manually. We need a modal that shows step-by-step manual installation instructions.
|
|
|
|
## Current Behavior
|
|
|
|
- A green "Install Warp plugin" chip appears in the CLI agent footer when the plugin isn't installed (`agent_input_footer/mod.rs:611-633`)
|
|
- Clicking it runs auto-install via `claude plugin` CLI commands (`plugin_manager/claude.rs:29-37`)
|
|
- On failure: an error toast appears with a link to logs
|
|
- On SSH: the chip visibility has a bug (see below)
|
|
|
|
## Chip Visibility Fix (Remote Sessions)
|
|
|
|
`should_show_install_plugin_button` hides the chip when `manager.is_installed()` returns true. But `is_installed()` reads the **local** filesystem (`~/.claude/plugins/installed_plugins.json`), not the remote machine's. In any remote session (warpified SSH, legacy SSH, Docker via SSH) where Claude Code runs on the remote, this check is wrong:
|
|
|
|
- Plugin installed locally but not on remote → chip hidden, user stuck with no instructions
|
|
|
|
Fix: the `CLIAgentSession` tracks an `is_remote` flag (set at session creation from `active_session_is_local()`). When `is_remote` is true, skip the `is_installed()` check and rely solely on whether the session has an active listener. If no listener → show the chip.
|
|
|
|
## Two Chip Modes
|
|
|
|
The chip has two modes depending on context:
|
|
|
|
### Mode 1: Auto-Install (current behavior)
|
|
|
|
**When:** local session, no prior install failure for this session.
|
|
|
|
- Chip label: "Install Warp plugin"
|
|
- Chip tooltip: "Install the Warp plugin to enable rich agent notifications within Warp"
|
|
- On click: runs auto-install (existing `handle_install_plugin` flow)
|
|
- On success: chip disappears (listener registers)
|
|
- On failure: transitions to Mode 2 for the rest of the session
|
|
|
|
### Mode 2: Manual Instructions Modal
|
|
|
|
**When:** SSH session, OR auto-install previously failed in this session.
|
|
|
|
- Chip label: "Plugin install instructions"
|
|
- Chip tooltip: "View instructions to install the Warp plugin"
|
|
- Chip icon: `Icon::Info` (instead of `Icon::Download`)
|
|
- On click: opens a modal with manual installation steps
|
|
|
|
## Modal Design
|
|
|
|
### Layout
|
|
|
|
Custom modal view following the `CodexModal` pattern (centered overlay, semi-transparent backdrop, Escape to close, click-outside to dismiss via `Dismiss` element).
|
|
|
|
- Title from `PluginInstallInstructions.title` (e.g. "Install Warp Plugin for Claude Code")
|
|
- Subtitle from `PluginInstallInstructions.subtitle`
|
|
- Numbered steps, each with:
|
|
- A short description of what the step does
|
|
- A monospace code block rendered via `render_code_block_plain` with a copy button
|
|
- Close button (X) in the top-right corner
|
|
- Copying a command shows a "Copied to clipboard" ephemeral toast
|
|
|
|
### Content for Claude Code
|
|
|
|
These are in-session slash commands (the user is already running Claude Code).
|
|
|
|
Step 1: "Add the Warp plugin marketplace repository"
|
|
```
|
|
/plugins marketplace add warpdotdev/claude-code-warp
|
|
```
|
|
|
|
Step 2: "Install the Warp plugin"
|
|
```
|
|
/plugins install warp@claude-code-warp
|
|
```
|
|
|
|
Step 3: "Reload plugins to activate"
|
|
```
|
|
/reload-plugins
|
|
```
|
|
|
|
Subtitle: "Ensure that jq is installed on your machine. Then, run these commands inside your Claude Code session."
|
|
|
|
Auto-install success toast: "Warp plugin installed. Please run /reload-plugins to activate."
|
|
|
|
### Extensibility
|
|
|
|
Each agent provides its own modal view. Common rendering helpers (backdrop, title bar, step layout, code blocks) are shared. Adding a new agent's modal means:
|
|
|
|
- Implementing a new view that uses the shared helpers
|
|
- Returning the appropriate view from a factory function keyed on `CLIAgent`
|
|
|
|
## State Tracking
|
|
|
|
### `plugin_install_failed` on `AgentInputFooter`
|
|
|
|
A per-session boolean (scoped to the `AgentInputFooter` instance) that tracks whether auto-install has failed. Set to `true` in the `handle_install_plugin` error callback. This determines whether the chip is in Mode 1 or Mode 2 for local sessions.
|
|
|
|
Reset to `false` if the plugin activates (listener connects — which already hides the chip entirely).
|
|
|
|
### No persistence across sessions
|
|
|
|
Failure state is not persisted. A new terminal session starts fresh in Mode 1 (auto-install).
|
|
|
|
## Behavior Summary
|
|
|
|
- Plugin active (listener present) → chip hidden
|
|
- Local, plugin installed on disk → chip hidden
|
|
- Local, plugin not installed, no prior failure → chip shown, Mode 1 (auto-install)
|
|
- Local, plugin not installed, prior failure → chip shown, Mode 2 (modal)
|
|
- Remote (any SSH), no listener → chip shown, Mode 2 (modal)
|
|
- Remote (any SSH), listener present → chip hidden
|
|
- Agent has no plugin support → chip hidden
|
|
- Install in progress → chip hidden
|
|
|
|
## Edge Cases
|
|
|
|
- **User installs plugin manually mid-session (without using the chip):** The listener will connect on next `SessionStart` event, chip disappears automatically.
|
|
- **User clicks chip in Mode 2 then installs manually:** Modal stays open until dismissed. Chip disappears on next render once listener is present.
|
|
- **Multiple terminal tabs with same agent:** Each tab has its own `AgentInputFooter` with independent failure tracking. This is correct — one tab's failure shouldn't affect another.
|
|
- **Warpified SSH (tmux wrapper):** Even though the local filesystem is accessible via tmux, the agent runs on the remote machine. The `is_remote` flag is set for all SSH sessions (warpified or legacy), so Mode 2 applies to all remote sessions.
|