Tmux

tmux

Use tmux when a task needs a persistent terminal state across tool calls.

Prerequisites

tmux -V

If tmux is not installed, stop and ask the user to install it.

Why tmux for Agents

tmux sessions survive SSH drops, terminal closes, and laptop sleep. This makes them ideal for AI agent workflows:

• Persistence — a long-running build or test suite continues even if your terminal disconnects.
• Detach/reattach — reconnect to a session hours later and see full scrollback.
• Isolation — each agent gets its own session with independent state.
• Observability — attach from another terminal to watch an agent work in real time.

Socket Convention

Use a dedicated socket directory:

SOCKET_DIR="${TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/tmux-agent-sockets}"
mkdir -p "$SOCKET_DIR"
SOCKET="$SOCKET_DIR/agent.sock"

Use short session names with no spaces. Target panes by window name (e.g. session:shell) rather than numeric index (e.g. session:0.0) — numeric indexes depend on base-index/pane-base-index settings and are not portable.

Quickstart

SESSION="agent-work"
tmux -S "$SOCKET" new-session -d -s "$SESSION" -n shell
tmux -S "$SOCKET" send-keys -t "$SESSION":shell -l -- "echo ready"
sleep 0.1
tmux -S "$SOCKET" send-keys -t "$SESSION":shell Enter
tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":shell -S -200

After creating a session, show monitor commands:

tmux -S "$SOCKET" attach -t "$SESSION"
tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":shell -S -200

Pane Targeting

Always use explicit targets. Never rely on the "active" pane — it changes when you split, select, or switch windows.

A target built from an empty variable does not error — it silently hits the active pane. tmux send-keys -t "$SESSION:" with $SESSION empty targets whatever window is currently active, which on a shared supervisor session is often the supervisor's own pane. This is how a misdirected send loses its intended recipient's context while looking like nothing went wrong. Any target assembled from a prior command's output needs an explicit non-empty check before it is used:

IDX=$(tmux list-windows -t "$SESSION" -F '#{window_index} #{window_name}' \
      | awk -v n="$WANT" '$2==n{print $1}')
[ -n "$IDX" ] || { echo "no window named $WANT" >&2; exit 1; }

Target formats

Layout-relative selectors

After a vertical split (split-window -v), use {top} and {bottom}. After a horizontal split (split-window -h), use {left} and {right}. Use {last} for the previously active pane.

Discover pane IDs

tmux -S "$SOCKET" list-panes -t "$SESSION":shell \
  -F '#{pane_id} #{pane_index} #{pane_width}x#{pane_height} #{pane_current_command}'

Use the %-ID (first column) when layout is unknown or complex.

Verify your target before sending

Before sending input to a pane, confirm it contains what you expect:

# Capture and check — is this the pane I think it is?
tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":shell.{bottom} -S -5

If the content doesn't match your expectation (wrong shell, wrong directory, unexpected output), you have the wrong target. Fix the target before sending.

Safe-State Verification

Before sending any input, verify the pane is in a state where your input will be interpreted correctly. This is the most common agent failure mode: correct pane, wrong pane state.

The problem

A pane might be:

• Running a command (your text queues in the terminal input buffer, executes after the current command finishes — or corrupts it)
• Showing an approval prompt (your text answers the prompt instead of going to the shell)
• Mid-edit in a TUI (your text inserts into an editor or REPL, not the shell)
• Processing a previous agent task (your new prompt interrupts or corrupts the current work)

The check

Always capture-pane and inspect the last few lines before sending:

OUTPUT=$(tmux -S "$SOCKET" capture-pane -p -J -t "$TARGET" -S -5)
echo "$OUTPUT"

What to look for:

What to do next — the action decision

After capturing, decide your next keystroke. Paste does not equal send. Text sitting in the input line has not been submitted until you press Enter — but pressing Enter blindly is the most common agent mistake.

Key distinctions:

• C-u clears the current input line without executing it — use when you see stale queued text.
• Escape dismisses TUI dialogs and prompts — use for agent approval UIs, editor prompts, or modal dialogs.
• C-c interrupts the running process — use for shell commands, streaming output, or hung processes. In some TUIs, C-c has a different meaning (copy), so check first.
• When uncertain, capture again. A second capture-pane costs nothing. A wrong keystroke can corrupt state.

Verify process state programmatically

# What process owns the pane right now?
tmux -S "$SOCKET" list-panes -t "$TARGET" \
  -F '#{pane_current_command} #{pane_pid}'

If pane_current_command is bash/zsh/fish, the shell is likely at a prompt. If it shows another process name (node, python, vim, claude), something is running — do not send shell commands.

Rule: Never send to a pane you haven't captured in this turn. Pane state changes between tool calls. Always capture, inspect, decide, then send.

Sending Input Reliably

Send text and Enter separately

tmux -S "$SOCKET" send-keys -t "$TARGET" -l -- "$cmd"
sleep 0.1
tmux -S "$SOCKET" send-keys -t "$TARGET" Enter

• Use -l (literal) for text payloads.
• Send Enter separately with a short delay.
• Send control keys separately (e.g. C-c, C-d).
• Do not combine text and Enter in one fast send for interactive agent TUIs.

Send Verification

After sending input, verify it landed. Two distinct checks using plain tmux:

Send confirmation

tmux -S "$SOCKET" send-keys -t "$TARGET" -l -- "echo hello-canary"
sleep 0.1
tmux -S "$SOCKET" send-keys -t "$TARGET" Enter
sleep 0.3
OUTPUT=$(tmux -S "$SOCKET" capture-pane -p -J -t "$TARGET" -S -10)
if echo "$OUTPUT" | grep -q "hello-canary"; then
  echo "SEND OK"
else
  echo "SEND FAILED — text not found in target pane"
fi

Response readiness

Poll capture-pane until you see the expected output or a shell prompt:

# Simple poll loop — wait up to 15s for a pattern
DEADLINE=$(($(date +%s) + 15))
while true; do
  OUTPUT=$(tmux -S "$SOCKET" capture-pane -p -J -t "$TARGET" -S -50)
  if echo "$OUTPUT" | grep -qE 'Done|ready|❯|\$'; then
    echo "Response detected"
    break
  fi
  if [ "$(date +%s)" -ge "$DEADLINE" ]; then
    echo "Timed out waiting for response"
    break
  fi
  sleep 0.5
done

Never skip send verification. "I sent it" is not the same as "the pane received it." Silent failures (wrong target, pane not ready, socket mismatch) produce no error — only verification catches them.

State Distinction

When working with tmux panes, distinguish these four states clearly:

Always confirm at least states 3 and 4 for critical operations.

Recovery

Wrong-target recovery

If you sent input to the wrong pane:

1. Detect: capture-pane -t $INTENDED_TARGET — your text is absent.
2. Find: capture-pane -t $WRONG_TARGET — your text appeared here instead.
3. Cancel: Send C-c to the wrong pane if the command is running.
4. Re-send: Send the input to the correct target.

# Cancel the accidental command in the wrong pane
tmux -S "$SOCKET" send-keys -t "$WRONG_TARGET" C-c
# Re-send to the correct pane
tmux -S "$SOCKET" send-keys -t "$CORRECT_TARGET" -l -- "$cmd"
sleep 0.1
tmux -S "$SOCKET" send-keys -t "$CORRECT_TARGET" Enter

Socket permission issues

# Check socket exists and permissions
ls -la "$SOCKET"

# Common fix: socket dir not writable
chmod 700 "$SOCKET_DIR"

# On shared systems, use TMUX_SOCKET_DIR to isolate
export TMUX_SOCKET_DIR="$HOME/.tmux-sockets"
mkdir -p "$TMUX_SOCKET_DIR"

Hung-process recovery

# Try interrupt first
tmux -S "$SOCKET" send-keys -t "$TARGET" C-c

# If still hung, kill the pane's process
PANE_PID=$(tmux -S "$SOCKET" display-message -t "$TARGET" -p '#{pane_pid}')
kill -9 "$PANE_PID"

Supervisor lanes

One agent supervising another in split panes — upward prompt flow, watcher loops, approval handling, recurring supervision — is in references/supervisor-lanes.md. The pane discipline above still applies: verify the target, check the state, send text and Enter separately, confirm it landed.

Long-Running TUIs

When a pane runs a TUI (agent CLI, REPL, editor):

• Do not guess state — always capture-pane before sending. The TUI may have advanced, errored, or prompted since you last looked.
• Detect TUI exit — check pane_current_command from list-panes. If it shows bash/zsh instead of the TUI process, the TUI has exited.
• Poll for readiness — use a capture-pane + grep loop with appropriate patterns and timeouts for TUI readiness markers.

# Check what process is running in the pane
tmux -S "$SOCKET" list-panes -t "$SESSION":shell \
  -F '#{pane_id} #{pane_current_command}'

Common Commands

# list sessions and panes
tmux -S "$SOCKET" list-sessions
tmux -S "$SOCKET" list-panes -a

# capture output
tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":shell -S -400

# interrupt running command
tmux -S "$SOCKET" send-keys -t "$SESSION":shell C-c

Agent CLI Patterns

Use one session per tool or repo for isolation.

# Claude Code
tmux -S "$SOCKET" new-session -d -s claude-main -n shell
tmux -S "$SOCKET" send-keys -t claude-main:shell -l -- "cd /path/to/repo && claude"
sleep 0.1
tmux -S "$SOCKET" send-keys -t claude-main:shell Enter

# Codex
tmux -S "$SOCKET" new-session -d -s codex-main -n shell
tmux -S "$SOCKET" send-keys -t codex-main:shell -l -- "cd /path/to/repo && codex"
sleep 0.1
tmux -S "$SOCKET" send-keys -t codex-main:shell Enter

When prompting these tools later, keep using the same session and split text/Enter.

Worktree Integration

For filesystem isolation between agents, create one git worktree per agent before starting tmux sessions, and keep worktree logic out of this skill. (A using-git-worktrees skill was referenced here previously; it is not installed and is not part of this collection.)

Pattern: one worktree per agent, one tmux session (or pane) per worktree.

Self-Test

Run the self-test script to verify tmux mechanics work in your environment:

bash "$(dirname "$0")/scripts/self-test.sh"   # or scripts/self-test.sh beside this SKILL.md

See scripts/self-test.sh — beside this file, wherever the skill is installed — for the full procedure. It creates an isolated tmux socket, verifies pane targeting, send verification, cross-pane isolation, and wrong-target recovery, then cleans up.

Cleanup

tmux -S "$SOCKET" kill-session -t "$SESSION"
tmux -S "$SOCKET" kill-server

Bundled scripts

All four sit in scripts/ beside this file.

References

• references/fundamentals.md — Session/window/pane structure, targeting, splits, resize, capture-pane, scrollback, environment variables, troubleshooting.

Notes

• tmux supports macOS/Linux natively. On Windows, use WSL.
• Prefer tmux for interactive tools, auth flows, and REPLs.
• Prefer normal exec/background jobs for non-interactive commands.
• For multi-agent lane orchestration, see references/supervisor-lanes.md. Use /loop (Claude Code) or a shell loop (other agents) for recurring supervision.