kitty-workbench/README.md

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. 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 (MCP) over stdio transport.

License

MIT