# kittymux

> kittymux turns kitty into a multiplexer for AI coding agents: a tab bar that shows which agent is working, which is waiting for you and which has finished, plus a docked panel, an inbox, a command palette and session restore. Local only; Linux; tested on kitty 0.49.1 and 0.49.2.

- [Documentation](/docs): Run coding agents in kitty and always know which one needs you. Install kittymux, learn the tab bar and deck, move panes, and fix what looks wrong.
- User guides: Install kittymux, read the tab bar, move panes, keep track of agents and restore sessions.
  - [Overview](/docs/users): 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.
  - [Getting started](/docs/users/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.
  - [Install and update](/docs/users/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.
  - [Platforms and compatibility](/docs/users/platforms): What has actually been run (kitty versions, desktops and agent CLIs) and what is only expected to work. Tested means a person or a test did it.
  - [What you can do](/docs/users/what-you-can-do): A map of everything kittymux adds to kitty, grouped by task, with what is shipped, in beta or planned. Start here to see if it can do something.
  - [Tabs and panes](/docs/users/tabs-and-panes): Move panes and tabs around: join a tab into another as splits, turn a pane into a tab, swap panes, jump by number and drag title bars.
  - [The tab bar](/docs/users/the-tab-bar): Read what each tab row says, tell look-alike tabs apart with the folder line, switch between sidebar, rail and hidden modes, and resize the bar.
  - [Peek, deck and panel](/docs/users/peek-deck-and-panel): Look at a tab you are not in without switching to it: a right-click peek card, the sidebar deck and the always-visible docked panel.
  - [Agent status](/docs/users/agent-status): The five states an agent can be in, how kittymux decides each from the screen and hooks, why a quiet screen never means waiting, and how to ask why.
  - [Notifications and inbox](/docs/users/notifications-and-inbox): What reaches you and when: one desktop notification per event, a bell that never moves your focus, an inbox for everything, and switches to quiet it.
  - [Launch and find agents](/docs/users/launch-and-find-agents): Start agents in a tab or split, find any of them in one searchable list, reopen a closed conversation, and fan a prompt out to several agents.
  - [Sessions and restore](/docs/users/sessions-and-restore): Save a workspace and restore it, with each agent window asking to resume its own conversation. Autosave, templates and what does not come back.
  - [Shortcuts](/docs/users/shortcuts): Every kittymux key and mouse gesture in one place, grouped by task, plus leader mode and the keymap overlay that lists your own shortcuts too.
  - [Your own shortcuts](/docs/users/your-own-shortcuts): How kittymux treats the keys you already use: which chords it avoids, how to find and resolve clashes, and how to rebind a kittymux key.
  - [Customization](/docs/users/customization): Choose which pieces of kittymux you use, set colours, layout and behaviour with switches and environment variables, and add your own agents.
  - [Troubleshooting](/docs/users/troubleshooting): Symptoms, likely causes and fixes: shortcuts that do nothing, an old-looking bar, missing logos, wrong notifications, early finishes and focus jumps.
  - [Privacy and security](/docs/users/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.
  - [CLI reference](/docs/users/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.
  - [Glossary](/docs/users/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.
- Developer: How kittymux is built, how to test a change safely, and what to work on next.
  - [Developer overview](/docs/developer): Where to start if you want to change kittymux: how it is built, how to test a change safely, how the docs stay honest, and what to work on next.
  - [Architecture](/docs/developer/architecture): How kittymux is built: pure modules, in-kitty pieces, kittens and scripts, the invariants that keep agent state honest, and the kitty behaviour it depends on.
  - [Contribute](/docs/developer/contribute): Set up an isolated worktree, run the test gates, follow the pull request checklist, and add an agent, a key or a page without touching live sessions.
  - [Testing](/docs/developer/testing): Run the unit tests and the real-kitty rigs without touching your own kitty, config or state, and see which edge cases still need a person.
  - [Docs maintenance](/docs/developer/docs-maintenance): How the docs are structured, written and checked, how the status table is generated, and how this folder becomes the published site.
  - [Release checklist](/docs/developer/release-checklist): What must be true before you announce a release, what is still open, and the claims to avoid. Early-adopter ready is the honest state today.
  - [Roadmap](/docs/developer/roadmap): What to work on next, in order: why each item matters, what blocks it and what done looks like. The docked panel on a real desktop comes first.