CLI reference
Every kittymux command with its options and an example, from the health check and layout switches to sessions, pick, fan-out, inbox and features.
Run kittymux help for the same list in your terminal. Commands that act on a kitty use the kitty they were started inside. Outside kitty, they use the newest socket you own.
kittymux doctor
Checks your install and tells you how to fix what is off: dependencies, the remote control socket, chords that clash with your window manager or with your own configuration, missing hook events, installed agents without a resume definition, and a kitty that was updated while it ran.
kittymux doctor
kittymux doctor --bundle [DIRECTORY]The bundle is a private local archive of generated versions, platform, feature switches and counts. It excludes configs, environment values, logs, screen text, titles, paths, commands and session identities. Nothing is uploaded.
kittymux demo
Opens an isolated kitty with a sample session, fake agents in different states and the real key bindings. Your configuration is never touched. Close the window when you are done.
kittymux hooks
Prints the Claude Code hook configuration.
kittymux hooks # print the snippet
kittymux hooks --install # merge it into ~/.claude/settings.json, after a backup
kittymux hooks --remove # remove exactly those entries, after a backupkittymux layout
Switches this kitty's bar on the fly. See The tab bar.
kittymux layout mode full|compact|hidden|cycle
kittymux layout edge left|right|bottom|top|cycle
kittymux layout width 30 # or +N and -N
kittymux layout preset NAME # sidebar, rail, right-sidebar, bottom, top, zen
kittymux layout pick # an fzf list of presets
kittymux layout show
kittymux layout default # pin this layout for new windows. "default clear" follows your last choice againkittymux inbox
Everything that wants your attention, newest first. See Notifications and inbox.
kittymux inbox [--all] [--json] [--limit N] [--waybar]
kittymux inbox ack ID… | --all
kittymux inbox clear [--all]
kittymux inbox jump [ID]
kittymux inbox watch
kittymux inbox ledger [--json]ledger answers how long agents waited on you: today, this week, the median and the longest, counted from when an event first appeared to when you first looked at it. See How long agents wait for you.
kittymux sessions
Saves and restores sessions with each agent's conversation. See Sessions and restore.
kittymux sessions [list]
kittymux sessions save [NAME] [--all] [--direct]
kittymux sessions restore [NAME|last] [--new-window]
kittymux sessions new NAME [--template T] [--agent A] [--agent2 B] [--cwd DIR] [--force]
kittymux sessions templates
kittymux sessions check
kittymux sessions history [--since 7d] [--json]
kittymux sessions recover [NAME] [--since 6h]
kittymux sessions autosave
kittymux sessions prepare
kittymux sessions rewrite FILE | --recentRestored agent windows ask before resuming. KITTYMUX_RESUME=auto skips the question.
kittymux spawn
Starts agents straight into a new tab or split of the focused kitty, in the current directory. See Launch and find agents.
kittymux spawn claude
kittymux spawn claude,codex,devin [--tab|--hsplit|--vsplit] [--cwd DIR]
kittymux spawn c x d u o a gkittymux pick
One searchable list: what needs you, every running agent, conversations you closed and a new agent.
kittymux pick [--menu rofi|fuzzel|fzf] [--list|--json] [--all] [--no-theme]kittymux pin
Keeps a conversation at the top of pick and out of the age limits. Also unpin, settle and unsettle.
kittymux pin [KEY | --window ID]
kittymux unpin
kittymux settle KEYalt+p and alt+s in the picker do the same on the selected row.
kittymux fanout
Sends one task to several agents, each in its own git worktree, branch and tab.
kittymux fanout "fix the login bug" claude,codex,devin [--name N] [--base REF]
kittymux fanout list
kittymux fanout compare NAME
kittymux fanout clean NAME [--yes] [--force]kittymux changes
What the agent in a window changed since its run started. It never writes into your repository.
kittymux changes [--window ID] [--files] [--diff] [--json] [--all]--diff shows the patch between the run baseline and the current private checkpoint. Output stops at 256 KiB or 2000 lines; --json --diff includes the patch and truncation metadata. Choose one window; --all --diff is rejected.
kittymux reopen
Reopens the most recently closed agent conversation in a new tab. It asks before resuming.
kittymux notify
Quiets popups and bells. Everything still lands in the inbox.
kittymux notify status
kittymux notify mute [1h]
kittymux notify unmute
kittymux notify off
kittymux notify on
kittymux notify done off|onkittymux snooze
No popups for one agent window for a while.
kittymux snooze [1h] [--window ID] [--clear]kittymux explain
Why each agent pane is in its state, and every recent decision: state changes and notifications sent or held back.
kittymux explain [--window ID] [--last N] [--all] [--json]kittymux features
Chooses which optional pieces of the bar you use. See The tab bar.
kittymux features [list]
kittymux features on NAME
kittymux features off NAME
kittymux features preset minimal|default|full
kittymux features -hkittymux panel
A persistent native kitty Wayland panel with Agents and Usage views. It stays open after actions. Bind its toggle in your window manager to reach it from any app.
kittymux panel [toggle|start|stop|status|summon|dock|wider|narrower]
kittymux panel width 40kittymux usage
Provider quotas, reset times and local activity. Inside kitty it opens an overlay in that kitty; outside kitty it opens a separate window. The pick menu includes a Usage entry. Live network quotas remain opt-in.
kittymux usage
kittymux usage --windowkittymux peek
Opens the peek card, what a right-click on a tab opens, over this pane. See Peek, deck and panel.
kittymux peek # the tab of this pane
kittymux peek TAB_ID # a tab of this kitty
kittymux peek --waiting # the agent that has waited on you longest (what ctrl+alt+shift+q runs)Exit status is 2 for an unknown option, and 1 when it is not started inside a kitty with a socket, when the tab does not exist or when nothing needs you.
kittymux palette
Opens the command palette over this pane, what ctrl+alt+shift+space opens. See the command palette.
kittymux paletteExit status is 2 for an argument, and 1 when it is not started inside a kitty with a socket or when no pane is focused. kittymux act JSON is what the palette runs after you choose. It is not meant to be typed: it refuses anything that is not one of the palette's own actions.
kittymux join
Moves this tab's panes into another tab as splits, keeping their shape. See Tabs and panes.
kittymux join # open the list of tabs
kittymux join --to TAB_ID [--side right|below|left|above|auto] [--pane]Exit status is 2 for an unknown option or a bad value, and 1 when it is not started from a pane of a kitty with a socket.
kittymux keys
Lists the chords that both your own kitty configuration and kittymux define. kittymux's file loads later, so its action is the one in effect. See Your own shortcuts.
kittymux keys [conflicts]kittymux dim
Dims the panes that are not focused, using kitty's own shader. It needs kitty 0.49.2 and the shader-slang package.
kittymux dim [on|off|toggle|show]kittymux screenshot
A PNG of this kitty window, rendered by kitty.
kittymux screenshot [--tab|--window] [FILE]kittymux upgrade
After a git pull: refreshes the links, reloads every running kitty twice and runs doctor.
kittymux uninstall
Shows what install.sh added. It is a dry run until you add --yes.
kittymux uninstall
kittymux uninstall --yes
kittymux uninstall --yes --purge # also deletes the state directorykittymux version
Prints the kittymux version.
kittymux workflow
Internal entry point used by the existing shell scripts. It validates the source kitty and pane, keeps command arguments intact and verifies scratch launch identity before closing a previous scratch tab. Keys and script names stay the same.
kittymux workflow nav prev|next|N
kittymux workflow newtab [--home] [--next]
kittymux workflow scratch [--cwd DIR] [-- COMMAND ARG…]
kittymux workflow find-session NAME
kittymux workflow save-session WINDOW_ID FILE
kittymux workflow session-names|session-current|session-active|session-last WINDOW_ID
kittymux workflow session-cycle WINDOW_ID prev|nextThe internal save-session helper saves the active named session of the owning OS window; an anonymous workspace saves only its anonymous panes. Parked named sessions are excluded. Use kittymux sessions save NAME --all for an explicit full-instance save.
sessions finalize FD PID CAPTURED_NS is an internal offline writer for inherited quit captures, not a user restore command.
Privacy and security
What kittymux reads, what it stores and where, what never leaves your machine, the trust boundaries it defends and how to report a vulnerability privately.
Glossary
The words kittymux uses, defined in one place - tab, pane, session, bar, rail, deck, panel, peek card, scanner, hook, inbox, journal, worktree and more.