kitty-workbench/INSTALL.md

# Kitty-Workbench — AI-Guided Setup

You are an AI assistant helping a user set up Kitty-Workbench. Follow these steps in order. Do not ask the user what they have — detect it yourself. Present options conversationally.

## Step 0: Clone and Install

If the repo is not already cloned locally, clone it:

```bash
git clone <repo-url>
cd kitty-workbench
```

Install the package:

```bash
pip install .
```

If `pip install` fails due to PEP 668, use:

```bash
pip install --break-system-packages .
```

Verify it installed:

```bash
kitty-workbench --version
```

If already installed, skip to Step 1.

## Step 1: Detect the Environment

Run these commands and collect the output. Do NOT ask the user — just run them:

```bash
# Python
python3 --version

# Platform
uname -s -r -m

# Terminal environment
echo "TERM_PROGRAM=$TERM_PROGRAM"
echo "KITTY_PID=$KITTY_PID"
echo "TMUX=$TMUX"
echo "VTE_VERSION=$VTE_VERSION"

# Available tools
which kitty 2>/dev/null && echo "kitty: found" || echo "kitty: not found"
which tmux 2>/dev/null && echo "tmux: found" || echo "tmux: not found"
which chafa 2>/dev/null && echo "chafa: found" || echo "chafa: not found"
which img2sixel 2>/dev/null && echo "img2sixel: found" || echo "img2sixel: not found"

# Access topology — is the user local, SSH'd, or on remote desktop?
echo "SSH_CONNECTION=$SSH_CONNECTION"
echo "DISPLAY=$DISPLAY"
echo "WAYLAND_DISPLAY=$WAYLAND_DISPLAY"
who am i 2>/dev/null

# Kitty remote control (only if kitty is installed)
kitty @ ls 2>&1 | head -1 || true

# SSH usage — does the user SSH to remote machines for work?
ls ~/.ssh/config 2>/dev/null && echo "ssh config: found" || echo "ssh config: not found"
grep -l "ControlMaster\|ControlPath" ~/.ssh/config 2>/dev/null && echo "ssh multiplexing: configured" || echo "ssh multiplexing: not configured"
ls ~/.ssh/sockets/ 2>/dev/null && echo "ssh sockets dir: exists" || echo "ssh sockets dir: missing"
ls ~/.ssh/known_hosts 2>/dev/null && wc -l < ~/.ssh/known_hosts 2>/dev/null && echo "known hosts (suggests SSH usage)" || true
```

## Step 2: Evaluate Options

Based on what you detected, determine:

### Access topology

- **Native** (no `$SSH_CONNECTION`, has `$DISPLAY` or `$WAYLAND_DISPLAY`): All backends work.
- **Remote desktop** (RDP/VNC session detected): All backends work — same as native.
- **SSH** (`$SSH_CONNECTION` is set): Only **tmux** works reliably for pane splitting. Kitty splits won't work (`kitty @` can't reach the user's local kitty instance). The plain backend can't open windows on the user's local machine.

### Available backends

| Backend | Requirement | Check |
|---------|------------|-------|
| **kitty** | `$KITTY_PID` set, or `kitty` on PATH + `kitty @ ls` succeeds | Best image quality, native splits. Only works for native/remote-desktop users. |
| **tmux** | `$TMUX` set, or `tmux` on PATH | Good image quality (sixel), works over SSH. Recommended default. |
| **plain** | Always available | Opens TUI in a separate terminal window. No splits. |

### Image protocol

| Protocol | Check |
|----------|-------|
| **kitty graphics** | Only if using kitty backend |
| **sixel** | `$TERM_PROGRAM` is one of: iTerm2, WezTerm, foot, contour, xterm, mlterm, mintty. Or `$VTE_VERSION` >= 7600 (GNOME Terminal 46+). Or `$TERM` contains "xterm-kitty". |
| **ASCII art** | `chafa` on PATH. Always works as fallback. |
| **none** | Plain text placeholder with file path. |

## Step 3: Present Options

Based on your evaluation, present the user's options conversationally. Be specific about what they have and what each option gives them.

**If over SSH:**
tmux works immediately for pane splitting, but images are limited to sixel or ASCII art. Present the user with options:

> "You're connected via SSH. Here are your options:
>
> **Option A: tmux (works now)** — I can split panes via tmux. Images render via sixel if your local terminal supports it, otherwise ASCII art. No setup needed.
>
> **Option B: Install kitty on the remote host + use a remote desktop** — If you can access this machine via a remote desktop protocol (Chrome Remote Desktop, RDP, VNC, etc.), you could install kitty on the remote host and use it through the remote desktop session. This gives you the full experience: native splits, best image quality. Is remote desktop an option for you?
>
> **Option C: Both** — Set up tmux now for SSH sessions, and also install kitty on the remote host for when you connect via remote desktop. Best of both worlds."

If the user chooses B or C, install kitty on the remote host:
- Linux: `curl -L https://sw.kovidgoyal.net/kitty/installer.sh | sh /dev/stdin`
- After install: add `allow_remote_control yes` to `~/.config/kitty/kitty.conf`
- Remind them: kitty's display features only work through a remote desktop session, not over SSH

If the user chooses A or C, set up tmux as normal (Step 4 handles mouse config).

**If native/remote desktop (sitting at the machine or RDP/VNC):**
**Recommend kitty** — it gives the best experience (native splits, best image quality via kitty graphics protocol). Present it as the primary recommendation, with tmux as the quick-start alternative if they don't want to install anything new.

However, warn about this caveat:
> **Note:** If you install kitty and use it as your terminal, be aware that some AI CLIs (like `gemini`) may prompt for passwords or authentication tokens during setup. Kitty uses its own keyboard protocol which can interfere with password prompts in some CLI tools. If you hit issues with password/auth prompts not working in kitty, switch to your regular terminal for that step, then come back to kitty.

Installation:
- Linux: `curl -L https://sw.kovidgoyal.net/kitty/installer.sh | sh /dev/stdin`
- macOS: `brew install --cask kitty`
- After install: add `allow_remote_control yes` to `~/.config/kitty/kitty.conf`
- Launch your AI CLI from within kitty to get the full experience

**If already in kitty:**
Great — they get the best experience. Just need `allow_remote_control yes` in kitty.conf. Note: existing kitty windows must be restarted for config changes to take effect.

**If no tmux and no kitty:**
Recommend kitty (best experience) or tmux (simplest install). Plain backend works but has no split panes — the TUI opens in a separate window.

## Step 4: Execute Setup

Based on what the user chose:

1. **Create project directory:**
   ```bash
   mkdir -p ~/Kitty-Workbench
   ```

2. **If kitty backend chosen**, ensure remote control is enabled:
   ```bash
   # Check if already configured
   grep -q "allow_remote_control" ~/.config/kitty/kitty.conf 2>/dev/null
   ```
   If not configured, add:
   ```bash
   mkdir -p ~/.config/kitty
   echo "allow_remote_control yes" >> ~/.config/kitty/kitty.conf
   ```

3. **If tmux backend chosen**, enable mouse support so the user can click widgets in the TUI pane:
   ```bash
   # Check current setting
   tmux show -g mouse 2>/dev/null
   ```
   If mouse is off or not set:
   ```bash
   tmux set -g mouse on
   ```
   To make it permanent, add to `~/.tmux.conf`:
   ```bash
   grep -q "set -g mouse on" ~/.tmux.conf 2>/dev/null || echo "set -g mouse on" >> ~/.tmux.conf
   ```
   Without this, tmux intercepts mouse clicks and the user cannot interact with checkboxes, buttons, or inputs in the display pane.

4. **If the user SSHes to remote machines** (detected by known_hosts having entries, or the user mentions remote work), **set up SSH ControlMaster** so the AI CLI can reuse the user's authenticated SSH connections without needing to re-enter passwords or touch physical keys:

   Ask the user: "Do you SSH into remote machines as part of your work? If so, I can configure SSH connection multiplexing — this lets you authenticate once, and my SSH commands piggyback on your open connection without needing a password."

   If yes:
   ```bash
   mkdir -p ~/.ssh/sockets
   chmod 700 ~/.ssh/sockets
   ```

   Check if ControlMaster is already configured:
   ```bash
   grep -q "ControlMaster" ~/.ssh/config 2>/dev/null && echo "Already configured" || echo "Not configured"
   ```

   If not configured, add to `~/.ssh/config` (create if needed):
   ```bash
   touch ~/.ssh/config
   chmod 600 ~/.ssh/config
   cat >> ~/.ssh/config << 'SSHEOF'

   # Kitty-Workbench: SSH connection multiplexing
   # First connection authenticates normally (password, key, etc.)
   # Subsequent connections reuse the tunnel — no re-auth needed
   Host *
       ControlMaster auto
       ControlPath ~/.ssh/sockets/%r@%h-%p
       ControlPersist yes
   SSHEOF
   ```

   Explain to the user how it works:
   > **How this works:** When you SSH into a remote machine, the connection stays open in the background for 10 minutes (`ControlPersist yes`). During that time, any other SSH command to the same host — including ones I run — reuses your authenticated tunnel. No password prompt, no key tap. The tunnel stays open until the original session closes or the connection drops — your key/auth provider handles its own timeout. Just open an SSH session to your target machine before asking me to work on it.

   If the user's `~/.ssh/config` already has Host-specific blocks, add the ControlMaster settings under a `Host *` block at the **end** of the file so it acts as a default without overriding specific host configs.

5. **Optional: install chafa** for ASCII art image fallback:
   - Linux: `sudo apt install chafa` or `sudo pacman -S chafa`
   - macOS: `brew install chafa`

## Step 5: Configure MCP

Add the Kitty-Workbench MCP server to the user's AI CLI configuration.

**Detect which CLI they're using** by checking for config files:

```bash
ls ~/.claude/settings.json 2>/dev/null && echo "Claude Code detected"
ls ~/.gemini/settings.json 2>/dev/null && echo "Gemini CLI detected"
ls ~/.config/gemini/settings.json 2>/dev/null && echo "Gemini CLI detected (alt path)"
```

**For Claude Code**, add to `~/.claude/settings.json` under `mcpServers`:
```json
{
  "mcpServers": {
    "kitty-workbench": {
      "command": "kitty-workbench",
      "args": ["mcp"]
    }
  }
}
```

**For Gemini CLI**, add to the appropriate MCP config.

**For other/unknown CLIs**, print the MCP configuration JSON and tell the user to add it to their CLI's MCP settings. The server command is `kitty-workbench mcp` on stdio transport.

## Step 6: Smoke Test

Verify everything works:

```bash
# Check the CLI works
kitty-workbench list

# Check the project directory exists
ls ~/Kitty-Workbench/
```

If the user is in tmux or kitty right now, you can also test the full flow:
- Call `kitt_open` with a test project
- Verify the TUI pane appears
- Call `kitt_close` to clean up

If not in the right terminal environment, skip the live test — it will work when they start a session later.

## Step 7: Write START.md

Write `~/Kitty-Workbench/START.md` — a personalized startup guide for this user's environment.

Include:
- Setup date
- Detected backend and image protocol
- Platform details
- MCP configuration that was applied (which CLI, what config)
- How to start a session (step by step for their specific setup)
- What optional packages are installed
- How to upgrade to a better backend later (if applicable)

Example:

```markdown
# Kitty-Workbench — Start Guide

**Setup date:** 2026-03-29
**Backend:** tmux
**Image protocol:** sixel
**Platform:** Linux (Ubuntu 24.04)

## Starting a Session

1. Open a tmux session (or use an existing one)
2. Start your AI CLI
3. Tell the AI to open a Kitty-Workbench project — it will call `kitt_open` and the display pane appears as a tmux split

## MCP Configuration

Configured in `~/.claude/settings.json`:
```json
{
  "mcpServers": {
    "kitty-workbench": {
      "command": "kitty-workbench",
      "args": ["mcp"]
    }
  }
}
```

## Environment

- Python: 3.11.4
- Textual: 0.79.0
- tmux: 3.4
- sixel: supported (GNOME Terminal 46)
- chafa: installed

## Upgrading

To switch to kitty backend later:
1. Install kitty
2. Add `allow_remote_control yes` to `~/.config/kitty/kitty.conf`
3. Launch your AI CLI from within kitty
4. Backend auto-detects — no config change needed
```

Adapt the content to match what you actually detected and configured. This file is for future AI sessions to read, so be precise.

## Done

Tell the user setup is complete and how to start their first session.