kittens

A collection of kittens for the kitty terminal, written in Rust.

It is a Cargo workspace: every kitten is a crate with its own binary and its own design document.

Kittens

Kitten	What it does
workspace	Isolated Linux environments inside kitty, backed by colima VMs. See the design.

Requirements

• Rust stable
• kitty 0.45 or newer
• colima 0.10 or newer

Installation

cargo install --path workspace

Note the absolute path of the binary, you need it for the next step:

command -v workspace || echo "$HOME/.cargo/bin/workspace"

Then in ~/.config/kitty/kitty.conf, replacing <PATH> with it:

allow_remote_control yes
listen_on unix:/tmp/kitty-{kitty_pid}

map cmd+shift+p launch --type=overlay --allow-remote-control <PATH> pick
map cmd+t       launch --type=tab    --cwd=current --allow-remote-control <PATH> inherit
map cmd+enter   launch --type=window --cwd=current --allow-remote-control <PATH> inherit

Use the absolute path, not the bare name. kitty launched from the Dock inherits launchd's PATH, which does not include ~/.cargo/bin, so it would not find the binary even though your shell does.

Then quit kitty entirely with cmd+q and open it again. Opening a new window is not enough, and neither is reloading the config (ctrl+cmd+,): listen_on only takes effect when the process starts, and without that socket kitten @ would have to talk over the same terminal the TUI is using.

cmd+t and cmd+enter replace kitty's native macOS shortcuts so that tabs and splits inherit their window's workspace. Outside a workspace they behave as they always did, with kitty's shell integration intact.

The listen_on path has to be short: macOS unix sockets are capped at 104 bytes and kitty discards anything longer without saying so.

Usage

Key	Action
cmd+shift+p	Open the picker: list, enter, create, delete, clean leftovers
cmd+t	New tab in the same workspace
cmd+enter	New split in the same workspace

Inside the picker: enter opens, n creates, d deletes, c cleans leftovers, q quits.

Inside a workspace

$HOME is the VM's own home, which is what keeps your dotfiles isolated per workspace. Your macOS home is mounted at the same absolute path it has outside, so paths work unchanged on both sides.

A workspace opens in the directory you launched it from whenever that directory lives under your macOS home, and ~/host points at that home so you can reach it with cd host.

Troubleshooting

Something like 2;10u appears when you press the shortcut. kitty is not intercepting the key, meaning the map is not loaded. Almost always kitty has not been fully restarted.

The overlay flashes and closes. The binary failed on startup. Errors now stay on screen waiting for Enter, so you should be able to read what happened.

It cannot find colima, docker or limactl. kitty launched from the Dock inherits launchd's PATH, without /opt/homebrew/bin. The binary already looks in the usual prefixes and hands that widened PATH to the processes it starts. If your tools live somewhere unusual, point at them with WORKSPACE_COLIMA, WORKSPACE_DOCKER, WORKSPACE_KITTEN or WORKSPACE_SYSCTL.

A new tab opens in /. The --cwd=current flag is missing from the keybinding.

A bare cd inside a workspace goes to the VM home, not your macOS home. That is what dotfile isolation means: $HOME belongs to the VM. Use cd host, or launch the workspace from the directory you want.

Development

cargo build --workspace
cargo test --workspace
cargo clippy --all-targets

Tests that query the real colima installation are marked #[ignore] so the normal suite does not depend on the state of the machine:

cargo test --workspace -- --ignored --nocapture

License

MIT — see LICENSE.