Advanced Kittens
Beyond icat, diff, themes, and hints, kitty ships with powerful kittens for remote work, automation, and extensibility. You can also write your own.
Master the advanced kittens — SSH, transfer, broadcast, panel, and custom kittens — to build a complete terminal automation workflow.
SSH Kitten
The ssh kitten connects to remote servers while automatically forwarding kitty's terminfo and supporting all kitty features (images, remote control, etc.).
Basic Usage
kitty +kitten ssh user@hostname
This is equivalent to ssh user@hostname but with automatic terminfo setup.
Without the SSH kitten, TERM=kitty on the remote may not be recognized. The kitten uploads the kitty terminfo file automatically, enabling full kitty protocol support — including icat, diff, and remote control — over the SSH connection.
Key Features
| Feature | Standard SSH | SSH Kitten |
|---|---|---|
| Terminfo forwarding | ❌ Manual | ✅ Automatic |
| Inline images (icat) | ❌ | ✅ |
| Remote control | ❌ | ✅ |
| Clipboard sharing | ❌ | ✅ |
| Config passthrough | ❌ | ✅ |
Configuration
# Set SSH kitten as default for remote connections
map ctrl+shift+enter kitten ssh
Transfer Kitten
Send and receive files over an existing TTY connection without setting up FTP, SCP, or a web server.
# Send a file to the remote
kitty +kitten transfer send /path/to/local/file
# Receive a file from the remote
kitty +kitten transfer receive /path/to/remote/file
# Send with progress
kitty +kitten transfer send --progress /path/to/large/file.iso
Transfer works over the TTY connection itself — no separate port needed. It is slow for large files but convenient for configs and scripts.
Choose Files Kitten
A fuzzy file picker for fast file navigation:
# Open a fuzzy file picker from current directory
kitty +kitten choose_files
# Start from a specific path
kitty +kitten choose_files /srv/myapp
# Filter by extension
kitty +kitten choose_files --pattern '*.py'
Command Palette Kitten
A searchable menu of all kitty actions:
# Open the command palette
kitty +kitten command_palette
Default shortcut: Ctrl+Shift+p
The command palette shows all available kitty commands with keyboard search. Type to filter, press Enter to execute.
Broadcast Kitten
Send keyboard input to multiple kitty windows simultaneously:
# Send a command to all windows
kitty +kitten broadcast "systemctl restart nginx"
# Start interactive broadcast mode
kitty +kitten broadcast
# Everything you type is sent to all matched windows
Useful for running the same command across multiple servers or environments.
Panel Kitten
Integrate kitty with desktop panels:
# Open a drop-down terminal in the panel
kitty +kitten panel
Custom Kittens — Write Your Own
You can write custom kittens in Python. A kitten is a Python script that implements a main() function.
Minimal Kitten
import sys
def main(args):
"""Print hello and the arguments received."""
print(f"Hello from kitten! Args: {args}")
return 0
if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))
Registering the Kitten
Kittens are discovered automatically from ~/.config/kitty/kitty/:
mkdir -p ~/.config/kitty/kitty/
Place your .py file there. The kitten name is the filename without .py.
Run Your Custom Kitten
kitty +kitten hello_kitten --name World
# Output: Hello from kitten! Args: ['--name', 'World']
Kitten with Terminal Interaction
from kitty.fast_data_types import get_options
from kittens.tui.handler import Handler
from kittens.tui.operations import styled
def main(args):
opts = get_options()
print(styled("Current colors:", bold=True))
print(f" Foreground: {opts.foreground}")
print(f" Background: {opts.background}")
print(f" Cursor: {opts.cursor}")
return 0
Advanced Kittens API
The kitty kitten API provides access to:
kitty.fast_data_types— terminal state, options, screen bufferkittens.tui.handler— TUI framework for interactive kittenskittens.tui.operations— styled text, cursor movement, input handlingkitty.options.types— Type definitions for configuration options
All Advanced Kittens Reference
| Kitten | Command | Primary Use |
|---|---|---|
ssh | kitty +kitten ssh user@host | SSH with terminfo forwarding |
transfer | kitty +kitten transfer send/receive | File transfer over TTY |
choose_files | kitty +kitten choose_files | Fuzzy file selection |
command_palette | kitty +kitten command_palette | Searchable command menu |
broadcast | kitty +kitten broadcast | Multi-window input |
panel | kitty +kitten panel | Desktop panel integration |
remote_file | kitty +kitten remote_file user@host:/path | Edit remote files locally |
show_key | kitty +kitten show_key | Debug key events |
unicode_input | kitty +kitten unicode_input | Unicode character picker |
Common Pitfalls
| Pitfall | Symptom | Fix |
|---|---|---|
| SSH kitten not using kitty terminfo | Remote has wrong TERM value | Verify kitty-terminfo is installed on remote |
| Custom kitten not found | kitten not found error | Place .py file in ~/.config/kitty/kitty/ |
| Transfer stalls on large files | No progress for minutes | Use scp or rsync for large transfers |
| Broadcast sends to wrong windows | Commands executed on wrong server | Check broadcast target filter |
| Panel kitten not working | No drop-down appears | Requires desktop environment with panel support |
Hands-On Practice
# SSH kitten test
kitty +kitten ssh localhost "echo 'Connected with kitty terminfo'"
# Transfer a small file
echo "test data" > /tmp/test-transfer.txt
kitty +kitten transfer send /tmp/test-transfer.txt
rm /tmp/test-transfer.txt
# Create and run a custom kitten
mkdir -p ~/.config/kitty/kitty
cat > ~/.config/kitty/kitty/uptime_kitten.py << 'EOF'
import subprocess, sys
def main(args):
result = subprocess.run(['uptime'], capture_output=True, text=True)
print(result.stdout.strip())
return 0
if __name__ == '__main__':
sys.exit(main(sys.argv[1:]))
EOF
kitty +kitten uptime_kitten
# Open the command palette
kitty +kitten command_palette