1---
  2name: working-with-tmux
  3description: Instructions for using tmux to spawn multiple processes, inspect them, and capture their output. Useful for running servers or long-running tasks in the background.
  4metadata:
  5  source: https://github.com/ampcode/amp-contrib
  6---
  7
  8This skill lets you manage multiple concurrent processes (like servers, watchers, or long builds) using `tmux` directly from the `Bash` tool.
  9
 10You can spawn new windows or panes to handle these tasks without blocking your main communication channel.
 11
 12## 1. Verify Environment & Check Status
 13
 14First, verify you are running inside tmux:
 15
 16```bash
 17echo $TMUX
 18```
 19
 20If this returns empty, you are not running inside tmux. Use `echo "agent-$(openssl rand -hex 3)"` to generate a unique session ID, then create a new session with a window named after what you're working on. You may skip step 2.1, creating the new window within an existing session.
 21
 22Once verified, check your current windows:
 23
 24```bash
 25tmux list-windows
 26```
 27
 28## 2. Spawn a Background Process
 29
 30To run a command (e.g., a dev server) in a way that persists and can be inspected:
 31
 321.  **Create a new detached window** with a specific name. This keeps it isolated and easy to reference.
 33
 34    ```bash
 35    tmux new-window -n "server-log" -d
 36    ```
 37
 38    _(Replace "server-log" with a relevant name for your task)_
 39
 402.  **Send the command** to that window.
 41    ```bash
 42    tmux send-keys -t "server-log" "npm start" C-m
 43    ```
 44    _(`C-m` simulates the Enter key)_
 45
 46## 3. Inspect Output (Read Logs)
 47
 48You can read the output of that pane at any time without switching your context.
 49
 50Get the current visible screen:
 51
 52```bash
 53tmux capture-pane -p -t "server-log"
 54```
 55
 56Get the entire history (scrollback, can produce _excessive_ tokens):
 57
 58```bash
 59tmux capture-pane -p -S - -t "server-log"
 60```
 61
 62Prefer to pipe the full scrollback buffer through grep/sed/tac/etc. to view just the content between your last command and the next prompt (exclusive).
 63
 64### Filtering between prompts
 65
 66When running commands on a remote shell, use `sed` to extract output between the shell prompt boundaries:
 67
 68```bash
 69tmux capture-pane -p -S - -t "ID" | sed -n '/PROMPT_PATTERN/,/PROMPT_PATTERN/{//d;p}'
 70```
 71
 72When prompts are long or appear in scrollback noise, generate random anchors to delimit output cleanly:
 73
 74```bash
 75A=$(openssl rand -hex 4)
 76echo "A: $A"
 77tmux send-keys -t "ID" "echo ${A}-st; YOUR_COMMAND; echo ${A}-end" C-m
 78sleep 1
 79tmux capture-pane -p -S - -t "ID" | sed -n '/^'"$A"'-st$/,/^'"$A"'-end$/{/^'"$A"'/d;p}'
 80```
 81
 82The `-st`/`-end` suffixes prevent matching the anchor inside the echoed command line.
 83
 84When scrollback becomes too noisy, clear it:
 85
 86```bash
 87tmux send-keys -t "ID" 'clear' C-m
 88tmux clear-history -t "ID"
 89```
 90
 91## 4. Interact with the Process
 92
 93If you need to stop or restart the process:
 94
 95**Send Ctrl+C (Interrupt):**
 96
 97```bash
 98tmux send-keys -t "server-log" C-c
 99```
100
101**Kill the window (Clean up):**
102
103```bash
104tmux kill-window -t "server-log"
105```
106
107## 5. Advanced: Chaining Commands
108
109You can chain multiple tmux commands in a single invocation using `';'` (note the quotes to avoid interpretation by the shell). This is faster and cleaner than running multiple `tmux` commands.
110
111Example: Create window and start process in one go:
112
113```bash
114tmux new-window -n "server-log" -d ';' send-keys -t "server-log" "npm start" C-m
115```
116
117## 6. Parallel Work
118
119Spin up multiple windows for independent tasks (downloads, research queries, builds):
120
121```bash
122for name in task-a task-b task-c; do tmux new-window -n "$name" -d; done
123```
124
125Send commands to each, then check results as they complete. Clean up finished windows:
126
127```bash
128tmux kill-window -t "task-a"
129```
130
131## Summary of Pattern
132
1330. `echo $TMUX`
1341. `tmux new-window -n "ID" -d`
1352. `tmux send-keys -t "ID" "CMD" C-m`
1363. `tmux capture-pane -p -t "ID"` (with anchor filtering for remote shells)