Seth/kitty-workbench
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: README, INSTALL.md (AI-guided setup)

Browse Source
This commit is contained in:
Mortdecai
2026-03-29 19:16:39 -04:00
parent e37b907326
commit f6a1cc4ebd
2 changed files with 410 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
INSTALL.md
+245
View File
@@ -0,0 +1,245 @@
# 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.
README.md
+165
View File
@@ -0,0 +1,165 @@
# Kitty-Workbench
An MCP server that gives your AI a rich, interactive display panel — right in your terminal.
You talk to the AI in one pane. It controls the other: pushing schematics, checklists, measurement tables, images, and live logs. You can interact back — check items off, input readings, click buttons. The AI sees your responses.
```
┌───────────────────────────┬──────────────────────────────────┐
│ AI CLI │ Kitty-Workbench display │
│ │ │
│ │ ┌────────┬───────────────────┐ │
│ > diagnose the HV │ │ CRT │ ☑ Check R412 │ │
│ focus circuit │ │ Focus │ ☐ Check R413 │ │
│ │ │ Schem │ ☐ Check C201 │ │
│ Measuring R412... │ │ │ │ │
│ Value: 1.05M ohm │ │ │ Voltage: [4.72] │ │
│ Expected: 910K │ │ │ [Record] │ │
│ Drifted +16.7% — FAIL │ ├────────┴───────────────────┤ │
│ │ │ 14:32 R412: 1.05M — FAIL │ │
│ │ │ 14:33 Replacing R412... │ │
└───────────────────────────┴──────────────────────────────────┘
```
## Setup
Give your AI the repo URL and tell it to set you up:
```
Clone https://github.com/yourorg/kitty-workbench and set it up for me
```
Or if you've already cloned it, open your AI CLI in the repo and say:
```
Read INSTALL.md and set me up
```
The AI clones the repo (if needed), installs the package, detects your terminal environment, walks you through your options, configures the MCP server, and writes a personalized `START.md` for future sessions.
That's it. The AI handles everything.
## What It Does
Kitty-Workbench is an [MCP server](https://modelcontextprotocol.io). Once configured, your AI CLI has access to these tools:
| Tool | What it does |
|------|-------------|
| `kitt_open` | Creates a project and opens the display pane |
| `kitt_display` | Pushes content — markdown, tables, checklists, buttons, text inputs |
| `kitt_image` | Displays images (schematics, photos, diagrams) |
| `kitt_layout` | Configures multi-region layouts (main + sidebar + log) |
| `kitt_log` | Records session log entries (saved to disk + shown in display) |
| `kitt_events` | Reads your interactions (checkbox toggles, button clicks, text input) |
| `kitt_close` | Closes the display pane and ends the session |
The AI generates all content. Kitty-Workbench is just the plumbing.
## Terminal Support
Kitty-Workbench auto-detects your terminal environment and adapts:
| Backend | Pane splitting | Image quality |
|---------|---------------|---------------|
| **kitty** | Native splits | Best (kitty graphics protocol) |
| **tmux** | tmux splits | Good (sixel, if your terminal supports it) |
| **Other** | Separate window | Good (sixel) or basic (ASCII art) |
You don't need kitty. You don't need tmux. Kitty-Workbench works in any terminal — it just gets better with more capable ones. The AI-guided setup explains your options and what each gives you.
### Remote Access
How you're connected to the machine running the AI matters:
| Access method | What works | What doesn't |
|---------------|-----------|-------------|
| **Native** (sitting at the machine) | Everything | — |
| **Remote desktop** (RDP, VNC, etc.) | Everything — same as native | — |
| **SSH** | **tmux only** | kitty splits, new windows |
**If you work over SSH, use tmux.** Here's why:
- **tmux works** because it runs on the same host as the AI. The AI calls `tmux split-window` and tmux creates the pane on the remote host. You see it through your SSH session. No special setup.
- **kitty splits don't work** because `kitty @` controls the kitty instance via a local Unix socket. When the AI runs on a remote host, it can't reach your local kitty. (Workaround: `kitten ssh` forwards the control protocol, but requires users to connect with `kitten ssh` instead of `ssh`.)
- **The "plain" backend can't open a window** on your local machine from a remote host. You'd have to manually open a second terminal and run the TUI yourself.
**Images over SSH:** Sixel and kitty graphics sequences are just terminal escape codes — they travel over SSH like any other output. Most modern terminals and SSH clients pass them through fine. If images don't render, your local terminal may not support the protocol, or your SSH config may be stripping escape sequences.
### Image Rendering
| Protocol | Quality | Terminals |
|----------|---------|-----------|
| Kitty graphics | Full color, alpha, animation | Kitty |
| Sixel | 256+ colors | GNOME Terminal 46+, Windows Terminal, iTerm2, foot, WezTerm, xterm |
| ASCII art | Block characters | Everything |
## Usage
Once set up, just talk to your AI. It decides when to use the display.
**Hardware diagnostic:**
> "I need to troubleshoot the focus circuit on this oscilloscope. Here's the service manual."
**Guided procedure:**
> "Walk me through replacing the capacitors on this PCB. Show me the layout and a checklist."
**Data collection:**
> "I need to measure and record voltages at 12 test points on this power supply."
The AI opens the display pane, builds the interface, and updates it as you work. Session logs are saved to disk in human-readable markdown — anyone can follow what happened without AI access.
## Project Data
Each session creates a project in `~/Kitty-Workbench/`:
```
~/Kitty-Workbench/
START.md # Personalized startup guide (created during setup)
io102/
session.md # Human-readable session log
session.jsonl # Machine-readable log (for AI session resume)
cost-log.jsonl # Session tracking
assets/ # Images, manuals, datasheets
```
Projects persist. Ask the AI to reopen one and it picks up where you left off.
## Requirements
- Python 3.10+
- Any terminal
- Any MCP-compatible AI CLI
## Platform Support
| Platform | Status |
|----------|--------|
| Linux | Full support |
| macOS | Full support |
| Windows | Via WSL2 |
## FAQ
**Do I need kitty installed?**
No. It works in any terminal. Kitty gives the best image quality, but tmux with sixel is excellent. The setup process will explain your options.
**Does it work in tmux?**
Yes. The TUI framework (Textual) works fully in tmux. Images render via sixel if your underlying terminal supports it.
**I SSH into a remote machine to work. What do I need?**
Use tmux on the remote host. It's the only backend that works reliably over SSH. The AI and tmux are on the same machine, so pane splitting works. Images travel over SSH as escape codes — if your local terminal supports sixel, you'll see them.
**Can I use kitty on my local machine to control a remote AI?**
Not easily. `kitty @` uses a local socket that the remote host can't reach. You can work around this with `kitten ssh` (which forwards kitty's control protocol), but tmux is simpler.
**Can I resume a previous session?**
Yes. Projects persist on disk. Ask the AI to open an existing project — it reads the session log to catch up.
**What AI CLIs work with this?**
Any that supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP) over stdio transport.
## License
MIT