Mortdecai
166 lines
7.6 KiB
Markdown
166 lines
7.6 KiB
Markdown
# 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://git.sethpc.xyz/Seth/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
|