domains / devops / tmux-session-automation / tmux

tmux

Skill card

combined

The two copies overlap on core tmux commands (sessions, windows, panes, send-keys, capture-pane) but each has material steps the other lacks. The first is a general reference covering session/window/pane management, keybindings, and a full workspace layout script. The second is a narrower, tool-specific skill for remote-controlling interactive CLIs via an isolated socket, with conventions for socket paths, safe literal sends, wait-for-text polling, Python REPL environment variables, and orchestrating multiple coding agents. Crowning one would hide the other's real alternative workflow.

Repositories

Other copies

Combined skill

---
name: tmux
description: Manage tmux sessions, windows, and panes for persistent remote workflows, interactive CLI control, and scripted terminal automation.
---

# tmux

Use tmux for persistent terminal sessions, multi-pane layouts, and remote-controlling interactive CLIs. Prefer bash background mode for non-interactive long-running tasks.

## Socket Conventions
- For isolated automation, use a private socket: `SOCKET_DIR="${CLAWDBOT_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/clawdbot-tmux-sockets}"; mkdir -p "$SOCKET_DIR"; SOCKET="$SOCKET_DIR/clawdbot.sock"`.
- Pass `-S "$SOCKET"` to every tmux command when using a private socket.
- For general use, the default socket is fine.

## Session Management
- Create detached session: `tmux new-session -d -s work`.
- Create detached session with size and command: `tmux new-session -d -s build -x 220 -y 50 "make all"`.
- Attach: `tmux attach -t work`.
- List: `tmux list-sessions`.
- Kill: `tmux kill-session -t work`.
- Check existence: `tmux has-session -t work 2>/dev/null`.
- Kill all on a socket: `tmux -S "$SOCKET" list-sessions -F '#{session_name}' | xargs -r -n1 tmux -S "$SOCKET" kill-session -t`.
- Kill server: `tmux -S "$SOCKET" kill-server`.

## Window Management
- New window: `tmux new-window -t work -n "logs"`.
- New window with command: `tmux new-window -t work:3 -n "server" "python -m http.server 8080"`.
- Select: `tmux select-window -t work:logs`.
- Kill: `tmux kill-window -t work:logs`.
- Move: `tmux move-window -s work:3 -t work:1`.

## Pane Management
- Split horizontal: `tmux split-window -h -t work:1`.
- Split vertical: `tmux split-window -v -t work:1`.
- Split with command: `tmux split-window -h -t work:1 "tail -f /var/log/syslog"`.
- Select: `tmux select-pane -t work:1.0`.
- Resize: `tmux resize-pane -t work:1.0 -R 20`.
- Zoom: `tmux resize-pane -Z`.
- Swap: `tmux swap-pane -s work:1.0 -t work:1.1`.
- Kill: `tmux kill-pane -t work:1.1`.

## Sending Input
- Send command with Enter: `tmux send-keys -t work:1.0 "ls -la" Enter`.
- Send literal text (safe for special characters): `tmux send-keys -t work:1.0 -l -- "$cmd"`.
- Send control key: `tmux send-keys -t work:1.0 C-c`.
- For Python REPLs, set `PYTHON_BASIC_REPL=1` before launching to avoid send-keys issues.

## Capturing Output
- Capture recent history: `tmux capture-pane -p -J -t work:1.0 -S -200`.
- Filter output: `tmux capture-pane -p -t work:1.0 | grep "ERROR"`.
- Wait for text: use a polling script or loop that checks `capture-pane` output for a pattern with a timeout.

## Scripting a Workspace Layout
```bash
#!/usr/bin/env bash
set -euo pipefail
SESSION="dev"
tmux has-session -t "$SESSION" 2>/dev/null && { tmux attach -t "$SESSION"; exit 0; }
tmux new-session -d -s "$SESSION" -n "editor" -x 220 -y 50
tmux send-keys -t "$SESSION:editor" "vim ." Enter
tmux split-window -h -t "$SESSION:editor"
tmux send-keys -t "$SESSION:editor.1" "npm test -- --watch" Enter
tmux new-window -t "$SESSION" -n "server"
tmux send-keys -t "$SESSION:server" "docker compose up" Enter
tmux split-window -v -t "$SESSION:server"
tmux send-keys -t "$SESSION:server.1" "tail -f logs/app.log" Enter
tmux new-window -t "$SESSION" -n "shell"
tmux select-window -t "$SESSION:editor"
tmux attach -t "$SESSION"
```

## Orchestrating Coding Agents
- Create multiple sessions: `for i in 1 2 3; do tmux -S "$SOCKET" new-session -d -s "agent-$i"; done`.
- Launch agents: `tmux -S "$SOCKET" send-keys -t agent-1 "cd /tmp/project1 && codex --yolo 'Fix bug X'" Enter`.
- Poll for completion by checking for shell prompt in `capture-pane` output.
- Use separate git worktrees for parallel fixes.

## Configuration
- Change prefix: `unbind C-b; set -g prefix C-a; bind C-a send-prefix`.
- Enable mouse: `set -g mouse on`.
- Start numbering at 1: `set -g base-index 1; setw -g pane-base-index 1`.
- Renumber windows: `set -g renumber-windows on`.
- Increase scrollback: `set -g history-limit 50000`.

## Cleanup
- Kill session: `tmux kill-session -t work`.
- Kill all on socket: `tmux -S "$SOCKET" kill-server`.