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:

git clone <repo-url>
cd kitty-workbench

Install the package:

pip install .

If pip install fails due to PEP 668, use:

pip install --break-system-packages .

Verify it installed:

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:

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

   mkdir -p ~/Kitty-Workbench
   

2. If kitty backend chosen, ensure remote control is enabled:

   # Check if already configured
   grep -q "allow_remote_control" ~/.config/kitty/kitty.conf 2>/dev/null
   

   If not configured, add:

   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:

   # Check current setting
   tmux show -g mouse 2>/dev/null
   

   If mouse is off or not set:

   tmux set -g mouse on
   

   To make it permanent, add to ~/.tmux.conf:

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

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:

{
  "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:

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

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