home / skills / ampcode / amp-contrib / tmux
This skill helps you manage multiple tmux windows and panes from Bash, enabling background tasks, log inspection, and seamless process control.
npx playbooks add skill ampcode/amp-contrib --skill tmuxReview the files below or copy the command above to add this skill to your agents.
---
name: tmux
description: 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.
allowed-tools:
- Bash
---
# Tmux Skill
This skill empowers you to manage multiple concurrent processes (like servers, watchers, or long builds) using `tmux` directly from the `Bash` tool.
Since you are likely already running inside a tmux session, you can spawn new windows or panes to handle these tasks without blocking your main communication channel.
## 1. Verify Environment & Check Status
First, verify you are running inside tmux:
```bash
echo $TMUX
```
If this returns empty, you are not running inside tmux and these commands will not work as expected.
Once verified, check your current windows:
```bash
tmux list-windows
```
## 2. Spawn a Background Process
To run a command (e.g., a dev server) in a way that persists and can be inspected:
1. **Create a new detached window** with a specific name. This keeps it isolated and easy to reference.
```bash
tmux new-window -n "server-log" -d
```
_(Replace "server-log" with a relevant name for your task)_
2. **Send the command** to that window.
```bash
tmux send-keys -t "server-log" "npm start" C-m
```
_(`C-m` simulates the Enter key)_
## 3. Inspect Output (Read Logs)
You can read the output of that pane at any time without switching your context.
**Get the current visible screen:**
```bash
tmux capture-pane -p -t "server-log"
```
**Get the entire history (scrollback):**
```bash
tmux capture-pane -p -S - -t "server-log"
```
_Use this if the output might have scrolled off the screen._
## 4. Interact with the Process
If you need to stop or restart the process:
**Send Ctrl+C (Interrupt):**
```bash
tmux send-keys -t "server-log" C-c
```
**Kill the window (Clean up):**
```bash
tmux kill-window -t "server-log"
```
## 5. Advanced: Chaining Commands
You 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.
Example: Create window and start process in one go:
```bash
tmux new-window -n "server-log" -d ';' send-keys -t "server-log" "npm start" C-m
```
## Summary of Pattern
1. `tmux new-window -n "ID" -d`
2. `tmux send-keys -t "ID" "CMD" C-m`
3. `tmux capture-pane -p -t "ID"`
This skill shows how to use tmux to spawn and manage background processes, inspect their output, and clean them up. It provides a concise pattern for creating detached windows, sending commands, capturing visible output or full scrollback, and interacting with running tasks. Use it to run servers, watchers, or long-running jobs without blocking your main shell.
The skill uses tmux windows (detached by default) as isolated execution contexts. Create a new window with tmux new-window -n "NAME" -d, send the command with tmux send-keys -t "NAME" "CMD" C-m, and read output using tmux capture-pane -p -t "NAME" or tmux capture-pane -p -S - -t "NAME" for full history. You can interrupt a process with tmux send-keys -t "NAME" C-c and remove the window with tmux kill-window -t "NAME".
How do I check I'm in tmux?
Run echo $TMUX; if it is empty you are not inside a tmux session and tmux-targeted commands may fail.
How can I get the full log history for a window?
Use tmux capture-pane -p -S - -t "NAME" to capture the entire scrollback buffer for that window.