Seth/kitty-workbench
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
edebdcbab0e7385d081c774e93ce50fa0555439f
kitty-workbench/INSTALL.md
T

11 KiB
Raw Blame History

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

# 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: 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. Do NOT recommend kitty for SSH users.

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:

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

    mkdir -p ~/.ssh/sockets
chmod 700 ~/.ssh/sockets

    Check if ControlMaster is already configured:

    grep -q "ControlMaster" ~/.ssh/config 2>/dev/null && echo "Already configured" || echo "Not configured"

    If not configured, add to ~/.ssh/config (create if needed):

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

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.
Reference in New Issue View Git Blame Copy Permalink