| name | tool-tmux |
| description | Use tmux for session orchestration, pane/window control, and resilient long-running terminal workflows. Trigger when the task needs terminal multiplexing or keybinding troubleshooting. |
tool-tmux
When To Use
- Manage persistent terminal sessions across restarts and disconnects.
- Verify keybindings, splits, windows, and session behavior.
- Coordinate concurrent logs/tests/commands in panes.
Trusted Commands
tmux new -A -s dev
tmux ls
tmux attach -t dev
tmux split-window -h
tmux split-window -v
tmux list-keys
tmux source-file ~/.tmux.conf
Safe Defaults
- Reuse named sessions with
new -A -s for idempotent workflows.
- Reload config with
source-file before restarting everything.
- Inspect running state (
tmux ls) before creating new sessions.
Common Pitfalls
- Terminal emulator shortcuts can be confused with tmux shortcuts.
- Nested tmux sessions cause keybinding conflicts.
- Config reload does not retroactively change shell startup behavior.
Output Interpretation
no server running means no active tmux server/session exists.duplicate session means the target name is already in use.
Why It Matters For Agents
- Long-running tasks become safer and easier to recover.
- Pane/session orchestration reduces context switching overhead.
Repo Conventions
- Keep keybindings aligned with repo templates and cheat sheet docs.
- Favor predictable session names for repeatable workflows.
Trigger Examples
- Should trigger: "Reload tmux config and verify split shortcuts."
- Should trigger: "Create a reusable tmux session for tests and logs."
- Should not trigger: "Parse JSON from an API response."
