Troubleshooting

Start with the health check. It lists what is off and how to fix it, and it covers most of the cases below.

kittymux doctor

A shortcut does nothingCopy Anchor Link

Cause. The chord never reached kitty, or another binding replaced it.

1. The window manager took it. Hyprland handles a global chord before kitty. kittymux doctor lists chords Hyprland binds that kittymux also uses. Check one yourself with hyprctl binds -j.
2. Another binding replaced it. kitty uses the last definition of a chord, and kittymux's keys load after yours. Run kittymux keys to list every chord both define. See Your own shortcuts.
3. It is not bound. Press ctrl+alt+/ and search for it. If it is missing, run kittymux upgrade.
4. tmux has focus. Only the keys tmux really binds pass through to it; everything else stays kitty's.

Fix. Rebind the chord in the template, or put your own map below the kittymux include lines. See Resolve a clash.

kittymux is not foundCopy Anchor Link

Cause. ~/.local/bin is not on your PATH.

Fix. Add export PATH="$HOME/.local/bin:$PATH" to your shell profile and open a new shell. Until then, run ~/kittymux/bin/kittymux. The installer prints this when it is needed.

The bar looks old after an upgradeCopy Anchor Link

Cause. kitty caches tab_bar.py for the life of a running instance.

Fix. Run git pull && kittymux upgrade. It refreshes the links and reloads every running kitty twice. A new kitty window picks up the new bar at once. If doctor says a kitty was updated while it was running, save with ctrl+alt+shift+s, quit that kitty and start it again.

Logos are missing or show as boxesCopy Anchor Link

Cause. The bundled icon font loads only when kitty starts. A glyph added to the font reaches a running kitty only after a restart.

Fix. Restart kitty once after the first install, and after an upgrade that adds a logo. Until then kittymux leaves the logo out instead of drawing a box. Your sessions come back through ctrl+alt+shift+s.

Notifications are doubled or missingCopy Anchor Link

Doubled. You removed the filter_notification line in kittymux.conf, or a program titles its own notification with an agent's name. Put the line back to have kittymux own agent notifications.

Missing. Check these in order:

1. kittymux notify status says whether notifications are off, or muted and for how long.
2. kittymux snooze may be active for that window. Run it inside the window with --clear.
3. You were looking at the agent, so nothing fires. Focusing an agent clears its cues.
4. The run was shorter than 15 seconds, or kittymux did not know how long it ran. Finished notifications need 15 seconds of known work.
5. You hit the rate limit: one per window every 10 seconds and five in total.
6. Your notification daemon is not running or has no icon support.

kittymux explain shows, for every notification, whether it was sent or why it was held back.

An agent shows as finished too earlyCopy Anchor Link

Cause. Without hooks, a quiet screen is the only evidence, so a pause between tool calls can look like the end.

Fix. Run kittymux hooks --install. With the Stop hook, only the agent's own word ends a turn. kittymux doctor says when a hook event is missing. Then run kittymux explain to see which evidence ended the turn. See When is something "done"?.

My own scripts cannot find kitty after I moved the socketCopy Anchor Link

Cause. Scripts written for listen_on unix:/tmp/mykitty look for /tmp/mykitty-<pid> and nowhere else. When the socket moves to ${XDG_RUNTIME_DIR}, they find no kitty. Their keys then seem to do nothing, with no error to read, because a key-bound background script has nowhere to print one.

What kittymux does. It keeps a link at /tmp/mykitty-<pid> that points to the real socket, so those scripts keep working. The link grants nothing: the socket sits in your private directory, and only you can open it. kittymux never replaces anything that is already at that path, and it removes the links of kitties that have exited. kittymux doctor says how many of your scripts depend on it.

Fix if it is missing. kittymux features on socketlink, then reload kitty (kittymux upgrade). For one kitty, right now: ln -s "$XDG_RUNTIME_DIR/mykitty-<pid>" /tmp/mykitty-<pid>.

A bell moves my focusCopy Anchor Link

Cause. A bell in an unfocused window makes kitty request attention, and some compositors answer by focusing that window and switching workspace. Hyprland does this when misc:focus_on_activate is on.

Fix. kittymux reads that option and turns the bell request off, so this should not happen. kittymux doctor reports it. On sway, KDE or GNOME, which kittymux does not inspect, set window_alert_on_bell no in your kitty.conf. To keep attention requests on anyway, touch ~/.local/state/kittymux/attention-on. See A notification never takes your focus.

The pointer is a hand over the bar edgeCopy Anchor Link

Cause. This is how kitty works, not a fault. It affects tabs with a single pane.

• Over the tab bar kitty always shows a hand, and ignores shape requests there.
• kitty hit-tests split borders, which is what produces the resize arrow, only in a tab with two or more panes. In a single-pane tab nothing under the pointer is a border.

What you get. In a tab with split panes, the pointer over the bar's divider is the native resize arrow, the same one you see over a divider between two panes. In a single-pane tab, the bar's last two columns are the grab zone and the pointer stays a hand. Dragging still resizes the bar.

What to do.

• Use the docked panel (ctrl+alt+shift+b). It is its own window and shows the resize cursor on its edge in every tab.
• Resize from the keyboard with ctrl+alt+shift+[ and ctrl+alt+shift+], or collapse to the rail with the « button.
• If the arrow in a split tab looks wrong, such as the wrong shape, offset or missing, the picture comes from your cursor theme. Check that the theme has sb_h_double_arrow and the aliases ew-resize and col-resize.

kittymux cannot change this from Python. The roadmap explains what would fix it in kitty: The resize arrow on the bar edge of a single-pane tab.

Join does not place panes as expectedCopy Anchor Link

• The target is not in the splits layout. Placement that keeps the old shape needs kitty's splits layout. In tall, grid, stack or another layout, kitty places the panes itself. See Limits.
• The list says there is no other tab. Join lists every tab but the one being moved. Open another tab first.
• A tab you expected is missing. Tabs in other OS windows are listed with other window. Clear the filter if you typed one.
• The command says to run it from a pane. kittymux join acts on the kitty and pane it is started from. Run it inside a kitty with allow_remote_control socket-only and a listen_on socket.
• The panes arrived narrow. Every pane has to fit in the target tab, so joining several panes into a small or already split tab leaves each little room. Press alt+shift+= to equalize the panes, or join into a wider tab.

Doctor warns about the remote control socketCopy Anchor Link

Cause. The recommended settings are allow_remote_control socket-only and listen_on unix:${XDG_RUNTIME_DIR}/mykitty. doctor warns when you use allow_remote_control yes or a socket in /tmp.

Why it matters. With yes, a program in a terminal can control kitty with an escape sequence, such as an agent's tool output or a file you cat. A socket in the world-writable /tmp can be created ahead of you by another local user. kittymux only talks to sockets you own.

Fix. Use the recommended lines. See Install and update.

A restored agent asks before it resumesCopy Anchor Link

Cause. This is on purpose. A restored agent window never silently re-enters a conversation.

What to press. ⏎ resumes, n starts a new conversation, s opens a shell and a resumes this and every other waiting prompt for two minutes. To skip the question, set KITTYMUX_RESUME=auto. See The restore prompt.

Collect evidenceCopy Anchor Link

When something is still wrong, these show what kittymux sees:

kittymux version
kitty --version
kittymux doctor
kittymux explain --last 20

For bar drag problems, start kitty with KITTYMUX_DEBUG=1. Errors go to ~/.local/state/kittymux/barsize-debug.log. Tab bar errors go to tab_bar-error.log in the same directory.

Report a problemCopy Anchor Link

Open an issue on GitHub with the output above, your window manager and what you expected. Report a vulnerability privately instead. See Privacy and security.