tmux-run

name	tmux-run
description	Run a command in a tmux pane/window/session and monitor its output for errors. Triggers: /tmux-run, 'run in tmux', 'run in the other pane', 'run on the left', 'run in a new window', 'run in a new session', 'monitor tmux', 'watch tmux'
user_invocable	true

Tmux Run & Monitor

Run a command in a tmux pane and continuously monitor its output, notifying the user via system notification if something fails.

Sandbox: All tmux commands require dangerouslyDisableSandbox: true (socket access at /private/tmp/tmux-*/).

Step 1: Determine or create the target pane

The user may specify where to run the command. Handle each case:

Case A: Existing sibling pane ("left pane", "other pane", "the pane on the right")

NEVER use relative targets like -t left or -t right — they resolve based on the focused pane, which is not yours. Instead, discover the correct pane ID (%<number>):

tmux list-panes -a -F '#{pane_id} #{pane_current_command} #{pane_current_path} #{window_name} #{pane_active}'

1. Find the pane running claude in the current working directory — that is your pane.
2. Find sibling panes in the same window (same window_name). The other pane (typically running zsh, bash, make, etc.) is the target pane.
3. If there are multiple candidates, prefer the one running a shell (zsh/bash) in the same or related project directory.
4. Record the pane ID (e.g., %119) and use it for ALL subsequent tmux commands.

Case B: New split pane ("split a pane", "open a new pane")

# Split horizontally (side by side)
tmux split-window -h -t %<YOUR_PANE_ID> -P -F '#{pane_id}'
# Split vertically (top/bottom)
tmux split-window -v -t %<YOUR_PANE_ID> -P -F '#{pane_id}'

Capture the printed pane ID from -P -F '#{pane_id}' for monitoring.

Case C: New window ("new window", "another window")

tmux new-window -P -F '#{pane_id}'

If the command should run in a specific directory:

tmux new-window -c '/path/to/dir' -P -F '#{pane_id}'

Case D: New session ("new session", "separate session")

tmux new-session -d -s '<session-name>' -c '/path/to/dir' -P -F '#{pane_id}'

After identifying or creating the target

Tell the user which pane ID you are using and why. Always store the %<number> ID — never rely on names or relative positions after this point.

Step 2: Send the command

tmux send-keys -t %<PANE_ID> '<command>' Enter

• Quote the command properly to avoid shell interpretation issues.
• If the user wants to run the command in a specific directory and the pane is already open, cd first:

  tmux send-keys -t %<PANE_ID> 'cd /path/to/dir && <command>' Enter
  

Step 3: Monitor output

Use periodic captures to check the pane output:

tmux capture-pane -t %<PANE_ID> -p -S -100

Existing output in the pane

The target pane may already contain output from previous commands. On your first capture (right after sending the command), note what's already there so you can distinguish old output from new output. Look for your sent command in the pane to find where new output begins. Only evaluate errors/success from output after your command was sent.

Timing

Choose wait times and polling intervals based on the command:

• Fast commands (ls, cat, simple scripts): no initial wait, poll every 5-10s
• Medium commands (build, test, npm install): 5s initial wait, poll every 15-30s
• Long commands (pulumi, terraform, make with infra): 10-15s initial wait, poll every 30-60s

Completion detection

Look for:

• Shell prompt returning (the user's prompt pattern)
• make: *** pattern (Makefile failures)
• error:, Error:, ERROR:, FAILED, fatal in output
• The pane's current command reverting to a shell (check with tmux list-panes -t %<PANE_ID> -F '#{pane_id} #{pane_current_command}')

Scroll back

If the visible pane doesn't show enough, increase -S value (e.g., -S -200, -S -500).

Background monitoring

Use run_in_background: true on sleep+capture commands so you can do other work while waiting.

What to report

• On success: Briefly summarize what completed and any notable outputs.
• On failure: Send a system notification (see below) AND tell the user in chat with:
  • Which step/command failed
  • The error message
  • Your analysis of the root cause
  • Suggested fix if you can determine one (read relevant source files to diagnose)

Step 4: System notification on failure

When a failure is detected, send a macOS notification:

osascript -e 'display notification "SUMMARY_HERE" with title "Command Failed" sound name "Basso"'

Keep the summary under 200 characters. Include the failing step name and a brief reason.

Important notes

• Only run the specifically requested command in tmux. Any other commands needed for the task (e.g., looking up information, reading files, searching code) should be run directly in Claude Code using the normal tools. Tmux is only for the command the user explicitly asked to run there.
• The user may ask you to do other work while monitoring. Use run_in_background: true for the sleep+capture commands to avoid blocking.
• If the pane's working directory changes or a new command starts, re-evaluate whether you're still monitoring the right thing.
• If the pane is in a different directory than needed, cd before running the command.