ks is a session manager for kitty. It creates named kitty tabs that pair Claude Code with a shell, tracks their state, and lets you jump between them from an interactive TUI or shell scripts.
The main TUI view lists every session with its live state and working directory.
Press n to open the repository picker. Browse everything ks has scanned or type to fuzzy-filter.
Each session runs Claude Code and a shell in the same tab, either split horizontally (default) or as separate tabs.
Press ? for the full keybindings.
You need kitty with remote control enabled and the Claude Code CLI on PATH. Go 1.25 or later is required to build from source.
make installThis builds ks and copies it to ~/code/bin/. Adjust the Makefile or copy the binary yourself if you prefer another location.
For everything else — first session, configuration, subcommands, hooks — see the docs below.
- Getting started — install, minimal config, first session
- Configuration —
~/.config/ks/config.yamlreference - TUI guide — modes, keybindings, state badges, trash and restore
- Command reference — every subcommand and flag
- Repo finder —
ks repoand its output formats - Hooks and state detection — how
ksknows what Claude is doing - Summary tab — the optional Haiku-powered session summary
- Architecture — package layout, data flow, extending
ks - Troubleshooting — common failures and fixes
The MCP server, search daemon, and zoekt integration that used to live in this repo now live in code-search-local (csl). ks kept the repo subcommand so the shell repo() helper keeps working.