| name | tmux-debugging |
| description | Use when changing tmux config or using tmux to debug something. |
Purpose
Use this skill to diagnose tmux behavior in a live development environment while preserving active sessions and panes.
Critical Safety Rule
Never kill the tmux server without asking the user first.
This includes commands such as:
tmux kill-server
pkill tmux
killall tmux
Prefer targeted, reversible inspection and reload commands. If a destructive command might be needed, explain the risk and ask for explicit confirmation before running it.
When To Use
Invoke this skill when the user mentions any of the following:
- tmux configuration, bindings, panes, windows, sessions, or status line behavior
~/.config/tmux/tmux.conf, TPM, tmux plugins, or tmux reload failures
- pane capture, window naming, session selection, or shell integration issues
- OpenCode, Neovim, zsh, or worktree behavior that depends on tmux
Default Workflow
- Confirm whether the current shell is inside tmux by checking
$TMUX or using tmux display-message -p.
- Inspect live state with read-only commands such as
tmux list-sessions, tmux list-windows, tmux list-panes -a, and tmux show-options -g.
- Read the relevant repo files before editing behavior, especially
.config/tmux/tmux.conf and related scripts under .zsh/, bin/, or .config/opencode/.
- Prefer reloading config with
tmux source-file ~/.config/tmux/tmux.conf over restarting tmux.
- If changing repo files, run the narrowest relevant syntax or formatting checks for those files.
Safe Debugging Practices
- Treat tmux as live user state, not a disposable test process.
- Avoid commands that close panes, windows, sessions, or the server unless the user explicitly asks for that outcome.
- If cleanup is necessary, prefer targeting a known test session with
tmux kill-session -t <name> after confirming it is safe.
- Capture diagnostics before changing configuration so behavior can be compared after reload.
- Preserve existing key bindings and plugin order unless the bug requires changing them.
Failure Modes To Avoid
- Running
tmux kill-server without explicit user approval
- Restarting tmux to test a config change when
source-file is sufficient
- Killing an attached session while the user may be working in it
- Assuming tmux plugin problems require deleting plugin directories before inspecting TPM state
- Editing shell integration without checking whether the behavior comes from
.zsh/015-tmux.zsh, .zshrc, .config/tmux/tmux.conf, or a plugin