This repository has no description
3.4 kB
112 lines
1---
2name: tmux
3description: Run long-running commands in a tmux session and capture their output. Use when you need to start a build/test/server that takes minutes, run multiple commands in parallel, or interact with a process across tool calls.
4---
5
6# Tmux Skill
7
8Drive `tmux` directly via shell commands — no MCP needed. Use this for any
9long-running task whose output you'll want to inspect later, or for processes
10that need to outlive a single Bash tool call.
11
12## Session naming convention
13
14All sessions you create must be prefixed with `claude-`. This keeps them
15namespaced and lets you find idle ones to reuse.
16
17## Find an idle session, or create one
18
19Before starting a new session, check whether an existing `claude-*` session
20is idle and reuse it. A session is "idle" if its current pane is at a shell
21prompt with no running command.
22
23```bash
24# List existing claude- sessions
25tmux list-sessions -F '#{session_name}' 2>/dev/null | grep '^claude-' || true
26
27# Create a fresh detached session
28tmux new-session -d -s claude-build
29
30# Create a session only if missing (idempotent)
31tmux has-session -t claude-build 2>/dev/null || tmux new-session -d -s claude-build
32```
33
34## Run a command and wait for it
35
36Send the command followed by a unique completion marker, then poll
37`capture-pane` until the marker appears.
38
39```bash
40SESSION=claude-build
41MARKER="__DONE_$$_$RANDOM__"
42
43tmux send-keys -t "$SESSION" "your-long-command; echo $MARKER" Enter
44
45# Poll until the marker shows up
46until tmux capture-pane -p -t "$SESSION" | grep -q "$MARKER"; do
47 sleep 2
48done
49
50# Capture the full output (scrollback included)
51tmux capture-pane -p -S - -t "$SESSION"
52```
53
54Use `Bash(run_in_background=true)` for the polling loop if you want to do
55other work while waiting.
56
57## Capture output
58
59```bash
60# Just what's currently visible
61tmux capture-pane -p -t claude-build
62
63# Full scrollback (everything since session start)
64tmux capture-pane -p -S - -t claude-build
65
66# Last 200 lines of scrollback
67tmux capture-pane -p -S -200 -t claude-build
68```
69
70`-p` prints to stdout. Without it, output goes to a paste buffer.
71
72## Run things in parallel
73
74Use multiple sessions or multiple windows in one session.
75
76```bash
77# Multiple sessions (independent, clean)
78tmux new-session -d -s claude-build -- bash -c 'nix build .#foo'
79tmux new-session -d -s claude-tests -- bash -c 'pytest'
80
81# Multiple windows in one session
82tmux new-session -d -s claude-work
83tmux new-window -t claude-work -n build -- bash -c 'nix build .#foo'
84tmux new-window -t claude-work -n tests -- bash -c 'pytest'
85tmux list-windows -t claude-work
86```
87
88Note: when a command passed via `--` exits, the window closes too. To keep
89the pane around for inspection, wrap with `bash -c 'cmd; exec bash'` or use
90the `send-keys` pattern above.
91
92## Inspect
93
94```bash
95tmux list-sessions # all sessions
96tmux list-windows -t claude-build # windows in a session
97tmux list-panes -t claude-build # panes in current window
98```
99
100## Clean up
101
102```bash
103tmux kill-session -t claude-build # one session
104tmux kill-server # everything (nuclear)
105```
106
107## When NOT to use tmux
108
109- One-shot commands that complete in seconds → just use `Bash` directly.
110- Commands you want to background but don't need to interact with later →
111 `Bash(run_in_background=true)` is simpler.
112- Anything that needs structured stdout/stderr separation — tmux merges them.