version: "1.0.1" name: kitten description: Control and interact with Kitty terminal windows - list windows, read output, send commands, and launch new terminals user_invocable: true

Kitten Terminal Remote Control

Control your Kitty terminal windows directly from the agent. See what's running in every terminal, send commands, and manage windows.

Quick Start: Get Oriented First

Always start with `summary` to see all your terminals at a glance:

python3 {{skill_dir}}/scripts/kitten_control.py summary

This gives you a complete markdown overview of ALL open terminals showing:

════════════════════════════════════════════════════════════════════════════════
##  WINDOW 172  │  🟡 ACTIVE  │  ✅ READY  │  🐚 shell
════════════════════════════════════════════════════════════════════════════════
 
| Property | Value |
|----------|-------|
| **Window ID** | `172` |
| **Status** | ✅ READY - Can receive commands |
| **Process** | 🐚 shell |
| **CWD** | `/Users/me/workspace/myproject` |
| **Git Branch** | `main` |
| **Session Age** | 2d ago |
 
**Quick commands:**
- Send text: `send-text -w 172 -e "your command"`
- Send Ctrl+C: `send-key -w 172 ctrl+c`
 

 
### What Summary Shows You
 
| Annotation | Meaning |
|------------|---------|
| **✅ READY** | Shell is at prompt, can receive commands |
| **⏳ BUSY** | Running a process, may need Ctrl+C first |
| **🐚 shell** | Idle shell |
| **🤖 agent** | AI agent (codex, claude, etc.) |
| **🔗 ssh** | SSH connection (shows target host) |
| **🔨 build** | Build process (make, npm, cargo) |
| **🌐 server** | Running server |
| **📝 editor** | vim, nvim, etc. |
| **Git Branch** | Current branch in that directory |
| **SSH Target** | Remote host for SSH sessions |
 
### Summary Options
 

Default: 20 lines from each window

python3 {{skill_dir}}/scripts/kitten_control.py summary

More context: 50 lines per window

python3 {{skill_dir}}/scripts/kitten_control.py summary -n 50

Just last command output (cleaner)

python3 {{skill_dir}}/scripts/kitten_control.py summary -e last_cmd_output

Full scrollback (large output)

python3 {{skill_dir}}/scripts/kitten_control.py summary -e all -n 100

 
---
 
## Interacting With Windows
 
Once you've identified a window from the summary, use its **Window ID** to interact:
 
### Send Commands
 

Send a command and press Enter

python3 {{skill_dir}}/scripts/kitten_control.py send-text -w 172 -e "git status"

Send text without Enter

python3 {{skill_dir}}/scripts/kitten_control.py send-text -w 172 "partial text"

Send Ctrl+C to interrupt

python3 {{skill_dir}}/scripts/kitten_control.py send-key -w 172 ctrl+c

Send other keys: escape, enter, tab, up, down, ctrl+d, etc.

python3 {{skill_dir}}/scripts/kitten_control.py send-key -w 172 escape

 
### Read Output
 

Get current screen content

python3 {{skill_dir}}/scripts/kitten_control.py get-text -w 172

Get last command's output (cleanest)

python3 {{skill_dir}}/scripts/kitten_control.py get-text -w 172 -e last_cmd_output

Get full scrollback

python3 {{skill_dir}}/scripts/kitten_control.py get-text -w 172 -e all

 
### Window Management
 

Focus a window

python3 {{skill_dir}}/scripts/kitten_control.py focus -w 172

Close a window

python3 {{skill_dir}}/scripts/kitten_control.py close -w 172

Launch new window in specific directory

python3 {{skill_dir}}/scripts/kitten_control.py launch --cwd /path/to/project

Launch new tab with title

python3 {{skill_dir}}/scripts/kitten_control.py launch --type tab --title "Build"

 
---
 
## Common Workflows
 
### Check on a build/process

1. Get summary to find the window

python3 {{skill_dir}}/scripts/kitten_control.py summary -n 10

2. Found window 236 running a build, get its output

python3 {{skill_dir}}/scripts/kitten_control.py get-text -w 236 -e last_cmd_output

 
### Run a command in an existing shell

1. Find a READY shell from summary

python3 {{skill_dir}}/scripts/kitten_control.py summary -n 5

2. Window 172 is ✅ READY, send command

python3 {{skill_dir}}/scripts/kitten_control.py send-text -w 172 -e "make test"

3. Check the result

python3 {{skill_dir}}/scripts/kitten_control.py get-text -w 172 -e last_cmd_output

 
### Stop a runaway process

Send Ctrl+C

python3 {{skill_dir}}/scripts/kitten_control.py send-key -w 236 ctrl+c

Or send SIGINT signal

python3 {{skill_dir}}/scripts/kitten_control.py signal -w 236 SIGINT

 
---
 
## Requirements
 
- Kitty terminal with `allow_remote_control yes` in kitty.conf
- The `kitten` command in PATH (comes with Kitty)