SKILL.md

name: working-with-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. metadata: source: https://github.com/ampcode/amp-contrib

This skill lets you manage multiple concurrent processes (like servers, watchers, or long builds) using tmux directly from the Bash tool.

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:

echo $TMUX

If 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.

Once verified, check your current windows:

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.

    tmux new-window -n "server-log" -d

    (Replace "server-log" with a relevant name for your task)

  2. Send the command to that window.

    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:

tmux capture-pane -p -t "server-log"

Get the entire history (scrollback, can produce excessive tokens):

tmux capture-pane -p -S - -t "server-log"

Prefer 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).

Filtering between prompts

When running commands on a remote shell, use sed to extract output between the shell prompt boundaries:

tmux capture-pane -p -S - -t "ID" | sed -n '/PROMPT_PATTERN/,/PROMPT_PATTERN/{//d;p}'

When prompts are long or appear in scrollback noise, generate random anchors to delimit output cleanly:

A=$(openssl rand -hex 4)
echo "A: $A"
tmux send-keys -t "ID" "echo ${A}-st; YOUR_COMMAND; echo ${A}-end" C-m
sleep 1
tmux capture-pane -p -S - -t "ID" | sed -n '/^'"$A"'-st$/,/^'"$A"'-end$/{/^'"$A"'/d;p}'

The -st/-end suffixes prevent matching the anchor inside the echoed command line.

When scrollback becomes too noisy, clear it:

tmux send-keys -t "ID" 'clear' C-m
tmux clear-history -t "ID"

4. Interact with the Process

If you need to stop or restart the process:

Send Ctrl+C (Interrupt):

tmux send-keys -t "server-log" C-c

Kill the window (Clean up):

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:

tmux new-window -n "server-log" -d ';' send-keys -t "server-log" "npm start" C-m

6. Parallel Work

Spin up multiple windows for independent tasks (downloads, research queries, builds):

for name in task-a task-b task-c; do tmux new-window -n "$name" -d; done

Send commands to each, then check results as they complete. Clean up finished windows:

tmux kill-window -t "task-a"

Summary of Pattern

  1. echo $TMUX
  2. tmux new-window -n "ID" -d
  3. tmux send-keys -t "ID" "CMD" C-m
  4. tmux capture-pane -p -t "ID" (with anchor filtering for remote shells)