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## 4. Interact with the Process
65
66If you need to stop or restart the process:
67
68**Send Ctrl+C (Interrupt):**
69
70```bash
71tmux send-keys -t "server-log" C-c
72```
73
74**Kill the window (Clean up):**
75
76```bash
77tmux kill-window -t "server-log"
78```
79
80## 5. Advanced: Chaining Commands
81
82You 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.
83
84Example: Create window and start process in one go:
85
86```bash
87tmux new-window -n "server-log" -d ';' send-keys -t "server-log" "npm start" C-m
88```
89
90## Summary of Pattern
91
920. `echo $TMUX`
931. `tmux new-window -n "ID" -d`
942. `tmux send-keys -t "ID" "CMD" C-m`
953. `tmux capture-pane -p -t "ID"`