Customization

kittymux is built so you can use all of it, some of it or none. Most settings are a switch you can flip from a shell or an environment variable, never a file you must hand-edit.

How a setting is decidedCopy Anchor Link

For anything with a switch, the first of these wins:

1. An environment variable, such as KITTYMUX_HUE=off.
2. A flag file in the state directory, such as ~/.local/state/kittymux/hue-off.
3. The default.

The state directory is $KITTYMUX_STATE if set, otherwise ${XDG_STATE_HOME}/kittymux, which is ~/.local/state/kittymux by default. Its mode is 0700 and the files in it are 0600.

Choose the pieces of the barCopy Anchor Link

kittymux features                  # what is on, and where each setting comes from
kittymux features off hue
kittymux features on folder
kittymux features preset minimal   # minimal, default or full
kittymux features -h               # help

folder, hue, collide, panetitle, motion, titles, sudo, loginprompt, pkgprompt and socketlink are live (the last three are notifications for a terminal waiting on you: see Notifications and the inbox). sheet and hover are planned: the switch is saved and the command says so, but nothing reads it yet. See The tab bar.

LayoutCopy Anchor Link

kittymux layout changes the bar of one kitty instance on the fly. See The tab bar. kittymux layout default pins the current layout as the start for new windows.

ColoursCopy Anchor Link

Every colour comes from your live kitty theme. To pin the accent, set KITTYMUX_ACCENT=#rrggbb. The default is your theme's active_border_color.

Switches and variablesCopy Anchor Link

Optional looksCopy Anchor Link

These need kitty 0.49.2 or later, and are never written to an older kitty's configuration.

• Clickable file:line. On by default when your kitty supports it. install.sh links open-actions.conf only if you have none; otherwise it prints the two lines to add.
• Dim the inactive pane. kittymux dim on, off, toggle or show. It is off by default and needs the shader-slang package, because kitty compiles shaders with slangc. Without it, the command says so instead of failing on every reload.
• Screenshot. kittymux screenshot [--tab|--window] [FILE] writes a PNG that kitty renders itself, by default to ~/Pictures/kittymux-<time>.png with mode 0600, because it can show anything that was on screen.

Usage HUDCopy Anchor Link

Press ctrl+alt+u for local numbers per provider. Each provider is one file in python/collectors/, found automatically. Codex reads its rollout rate-limit snapshots, Claude shows a reconstructed five-hour window and weekly burn, Cursor shows its plan and share of AI lines, and Devin shows session and token activity. Real local numbers or "unavailable", never made-up ones. The overlay paints at once with placeholders, then each provider fills in as it finishes.

The local five-hour Claude bar is elapsed time, not quota consumed. Daily token charts use exact, dated Claude log counters, and old rolling-week totals are left out rather than relabelled as daily burn. Devin's local activity is the cumulative total for sessions modified today, so it is not recorded in the daily chart.

With KITTYMUX_USAGE_LIVE=1, collectors that offer a live call also fetch real quotas, cached for at least five minutes: Claude through its OAuth usage endpoint, Cursor through its dashboard service and Devin through its seat management service. The network is strictly opt-in, and everything works offline. A failed request backs off for five minutes while the previous rows stay visible with a stale note. Credentials are sent through curl's standard input, never its arguments.

To add a provider, drop a file in python/collectors/ with two functions: collect() for pure local reads that spawn nothing, and optionally live(cached) for the network call. A broken collector can never take down the HUD.

Agents you addCopy Anchor Link

Resume and prompt forms are data, not code. See Add an agent for resume, and Launch and find agents for fan-out prompts.