Getting started
Try kittymux in an isolated window, install it, run the health check and spend your first five minutes with the bar, the deck, agents and split panes.
The fastest way to see what kittymux does is the demo. It opens its own kitty window with its own configuration and state, a sample session and a few fake agents in different states. Your real configuration is never read or changed, and closing the window removes it.
Before you start
You need kitty 0.48 or later on Linux, plus jq, python3, fzf and git. kitty 0.49.2 adds
clickable file references, pane title bars and the native resize arrow. See Install and
update for the full list.
Set up in four steps
Try the demo
git clone https://github.com/KitsuneKode/kittymux ~/kittymux
~/kittymux/bin/kittymux demoPress ctrl+alt+b for the deck and ctrl+alt+y to jump to the agent that is waiting. Press ctrl+space, then ?, to see leader mode. Close the window when you are done.
Install
~/kittymux/install.shThe installer checks its dependencies, backs up kitty.conf and adds a few include lines. It never overwrites a file of yours. Add --leader to also turn on the tmux-style prefix.
Check the install
kittymux doctordoctor lists anything that is off and says how to fix it: a missing dependency, a remote control socket that is too open, a shortcut that clashes with your window manager, or a kitty that was updated while it kept running.
Add agent hooks
kittymux hooks --installThis merges Claude Code's status hooks into ~/.claude/settings.json, after making a backup. The hooks let an agent say "tool finished, still working" and "session ended", which keeps a quiet screen from being mistaken for "finished". Other agents work from the screen alone. kittymux hooks --remove takes exactly those entries back out.
Your first five minutes
Do these in a normal kitty window after installing.
- See every key. Press
ctrl+alt+/. Type a word to search, such aspaneordeck. Oneesccloses it. - Start an agent. Press
ctrl+alt+shift+o, thencfor Claude,xfor Codex,dfor Devin. Holdshiftwith the letter to start it in a split instead of a new tab. - Read the bar. A spinner means working.
!means it is asking you something.⊘means it hit a usage limit.✓means it finished while you were elsewhere. See Agent status. - Jump to the one that needs you. Press
ctrl+alt+y. Repeat to go to the next one, longest-waiting first. - Look without leaving. Right-click a tab for its peek card, press
ctrl+alt+shift+qfor a quick look at the agent that has waited longest, or pressctrl+alt+bfor the deck. See Peek, deck and panel. - Split, then join. Press
ctrl+alt+enterto split a pane below. Pressctrl+alt+shift+jin another tab to move all of its panes into the tab you pick. See Tabs and panes. - Save the workspace. Press
ctrl+alt+shift+s. After a crash,kittymux sessions restore lastbrings it back, and each agent asks before resuming its conversation. See Sessions and restore.
More to try in the demo
| Tab | Try | You should see |
|---|---|---|
| panes | ctrl+alt+e | A digit on every pane. Press one and that pane takes focus. |
| panes | ctrl+alt+shift+y, then a digit | The focused pane swaps with that one. |
| panes | ctrl+alt+d | The focused pane becomes its own tab. |
| panes | ctrl+alt+shift+c | A title bar on every pane. Drag one onto the bar to move a split. |
| file-refs | ctrl+shift+click on src/app.py:42:7 | Your editor opens at line 42. A made-up path opens nothing. |
| scrollback | ctrl+alt+PgUp and ctrl+alt+PgDn | The view moves a page back and forward. |
| any | Right-click a tab | A peek card with the tab's state, panes and the tail of its screen. |
Run commands inside the demo
kittymux screenshot, kittymux dim and similar commands act on the kitty they are started
from. Start them from a shell pane inside the demo, or they will act on your real window.
Next steps
- What you can do is the map of every capability.
- Shortcuts lists every key.
- If something looks wrong, start with Troubleshooting.
Overview
The user guides for kittymux, grouped by what you are trying to do - get set up, work every day, keep agents in view, and fix problems.
Install and update
Requirements, what the installer adds to your kitty configuration, the remote control settings kittymux recommends, and how to upgrade or remove it.