aelaguiz/kitten

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`

```last 20 lines of terminal output...```

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)