Kittens Introduction

Kittens are extensions for kitty — small programs that use the kitty protocol to add new functionality. They are written in Python and communicate with kitty through its internal API.

Learning Focus

Understand the kitten architecture and learn to run, list, and manage built-in kittens so you can extend kitty's capabilities without leaving the terminal.

What Are Kittens

A kitten is a standalone Python script that kitty launches and communicates with via a special protocol. Kittens can:

Access kitty's internal state (windows, tabs, buffers)
Render content directly to the terminal
Process user input and respond interactively
Chain together to build complex workflows

Key Insight

Kittens are not plugins in the traditional sense — they are separate processes that talk to kitty over a pipe. This makes them safe, isolated, and easy to write.

How Kittens Work

┌─────────────────────────────────────────────┐
│                  Kitty Process                │
│  ┌─────────┐  ┌─────────┐  ┌──────────────┐ │
│  │  Main   │  │  Event  │  │  Kitten      │ │
│  │  Loop   │  │  Loop   │  │  Manager     │ │
│  └────┬────┘  └────┬────┘  └──────┬───────┘ │
│       │            │              │          │
└───────┼────────────┼──────────────┼──────────┘
        │            │              │
        ▼            ▼              ▼
┌──────────────────────────────────────────────┐
│              subprocess.Popen                 │
│  ┌──────────┐  ┌──────────┐  ┌────────────┐ │
│  │  icat    │  │  diff    │  │  themes    │ │
│  │  kitten  │  │  kitten  │  │  kitten    │ │
│  └──────────┘  └──────────┘  └────────────┘ │
│  Each kitten = separate Python process        │
└──────────────────────────────────────────────┘
        │
        ▼
┌──────────────────────────────────────────────┐
│         Kitty Protocol (stdin/stdout)         │
│  - Query window dimensions                    │
│  - Send escape codes for images               │
│  - Read keyboard input                        │
└──────────────────────────────────────────────┘

Each kitten starts as a child process and communicates with kitty using the kitty protocol over standard input/output.

Running a Kitten

All kittens are invoked with the same syntax:

kitty +kitten <kitten-name> [arguments...]

Examples:

# Show an image inline
kitty +kitten icat image.png

# Compare two files side by side
kitty +kitten diff file1.txt file2.txt

# Open interactive theme browser
kitty +kitten themes

tip

You can also use tab-completion: type kitty +kitten and press Tab to see available kittens.

Listing Available Kittens

# List all built-in kittens
kitty +kitten ls

Output example:

icat                 Display images inline
diff                 Side-by-side file comparison
themes               Browse and apply color themes
hints                Select visible text interactively
hyperlinked_grep     Grep with clickable results
ssh                  SSH with automatic terminfo forwarding
transfer             Send/receive files over TTY
show_key             Debug key events
panel                Desktop panel integration
remote_file          View/edit remote files
choose_files         Fuzzy file selection
command_palette      Quick command access
broadcast            Send input to multiple windows

Built-in Kittens Overview

Kitten	Purpose	Typical Use
`icat`	Display images inline	View screenshots, plots, diagrams
`diff`	Side-by-side file diff	Code review, config comparison
`themes`	Interactive theme picker	Change color scheme visually
`hints`	Select visible text by search	Open URLs, copy paths, select text
`hyperlinked_grep`	Grep with clickable results	Search code, jump to matches
`ssh`	SSH with terminfo forwarding	Remote sessions with full kitty support
`transfer`	File transfer over TTY	Send files to/from remote servers
`show_key`	Debug key sequences	Learn key codes for binding
`remote_file`	Edit remote files locally	Quick remote config edits
`choose_files`	Fuzzy file picker	Fast file navigation
`command_palette`	Searchable command menu	Discover kitty actions
`broadcast`	Send input to multiple windows	Run commands on many servers
`panel`	Desktop panel widget	Quick terminal access from panel
`unicode_input`	Unicode character picker	Insert special characters

Running Kittens Without kitty +kitten

Some kittens can also be run directly as standalone commands:

# Direct invocation
kitty +runpy 'from kittens.icat.main import main; main()'

Or if symlinked into your PATH:

kitten icat image.png    # if kitten is symlinked

Common Pitfalls

Pitfall	Symptom	Fix
Forgetting `+kitten` syntax	`kitty icat: command not found`	Always use `kitty +kitten icat`
Running outside kitty	Kitten fails silently	Kittens only work inside kitty terminal
Missing Python dependency	Import error on launch	Install requirements with pip
Piping output that contains images	Garbled terminal	Use `--transfer-mode file` for scripts

Hands-On Practice

# List all available kittens
kitty +kitten ls

# Run the show_key kitten to debug keypresses
kitty +kitten show_key
# Press some keys, then Ctrl+C to exit

# Run the unicode_input kitten
kitty +kitten unicode_input
# Search for "arrow" and insert a character

What Are Kittens​

How Kittens Work​

Running a Kitten​

Listing Available Kittens​

Built-in Kittens Overview​

Running Kittens Without kitty +kitten​

Common Pitfalls​

Hands-On Practice​

What's Next​