# 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
```

## 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:**
Tell the user tmux is their only practical option. If tmux is installed, recommend it. If not, recommend installing it (`apt install tmux` / `brew install tmux`). Mention that images will work if their local terminal supports sixel.

**If native/remote desktop with tmux available:**
Present tmux as the ready-now option. Optionally mention kitty as an upgrade for better image quality if they want to install it later.

**If native/remote desktop in kitty:**
Great — they get the best experience. Just need `allow_remote_control yes` in kitty.conf.

**If no tmux and no kitty:**
Recommend installing tmux (simplest) or kitty (best experience). Plain backend works but has no split panes.

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