Tmux Remote Control

Tmux Skill

Simple, reliable tmux orchestration. Defaults to the current session the agent is running in.

Critical Rules

1. Current session by default. All scripts auto-resolve the current tmux session via $TMUX. Do NOT target other sessions unless the user explicitly names one.
2. Never create or destroy sessions unless explicitly instructed.
3. Never switch to a random session. If you need a pane, create a new window in the current session (tmux new-window) rather than hijacking another session.
4. Never target the agent's own pane. tmux-exec.sh refuses if you try (detected via $TMUX_PANE).
5. Respect busy panes. tmux-exec.sh tracks running commands. If a pane is busy it will refuse with details (command, elapsed time). Do not send C-c unless the user asks — instead wait and retry, or use a different pane.
6. No default timeout. tmux-exec.sh waits until the command finishes. Only pass -t when you have a good reason and understand that timeout ≠ cancellation — the command keeps running.
7. Verify before acting. Use tmux-list.sh to confirm targets exist (it also shows busy state).

Pane Targeting

Format: {session}:{window}.{pane} or {window}.{pane} (current session implied)

Script Location

All scripts live in the scripts/ directory alongside this SKILL.md file. The canonical source is ~/shalomb/agent-skills/skills/tmux/scripts/, hardlinked into each agent's skill directory (e.g. {SKILLS_DIR}/tmux-remote-control/scripts/, ~/.claude/skills/tmux/scripts/).

The skill file's own location tells you where the scripts are. When this skill is loaded, note the path it was read from and derive the script directory from it:

<skill-file-path>  →  $(dirname <skill-file-path>)/scripts/

For example, if this file was read from {SKILLS_DIR}/tmux-remote-control/SKILL.md, the scripts are at {SKILLS_DIR}/tmux-remote-control/scripts/.

Never use ./scripts/ — that resolves against the agent's current working directory (the project repo), not the skill directory.

⚠️ Critical Limitation: tmux-exec.sh Runs in a Subshell

tmux-exec.sh wraps every command in a new subshell inside the pane. This means:

• Environment variables set inside the command (export FOO=bar) do not persist to the pane's parent shell after the command exits.
• Commands that source credentials into the shell (e.g. aws-login, eval $(...), . ~/.env) will appear to succeed but have no effect on subsequent tmux-exec.sh calls.

Rule: For any command that must mutate the pane's shell environment, use raw tmux send-keys to type directly into the pane's own shell, then scrape the output with tmux-read.sh once the prompt returns:

# WRONG — tmux-exec.sh ALWAYS uses a subshell, even with -w.
# aws-login sources creds into that subshell, which exits immediately.
# The pane's parent shell never sees the credentials.
$SKILL_SCRIPTS/tmux-exec.sh "1.0" "aws-login my-account"       # subshell, creds lost
$SKILL_SCRIPTS/tmux-exec.sh -w '\$' "1.0" "aws-login my-account"  # still a subshell!

# CORRECT — type directly into the pane's own shell via send-keys
SESSION=$(tmux display-message -p '#{session_name}')
tmux send-keys -t "${SESSION}:1.0" "aws-login my-account" Enter
sleep 5   # allow login to complete (adjust for slow SSO)
$SKILL_SCRIPTS/tmux-read.sh "1.0"   # scrape output to confirm success

After the pane's shell has credentials set via send-keys, subsequent tmux-exec.sh calls for AWS CLI queries work fine — those subshells inherit the pane's exported env vars. Only the credential-sourcing step itself requires send-keys.

1. Execute (scripts/tmux-exec.sh)

Primary tool. Sends a command, waits for completion, returns output + exit code.

Shell Mode (default)

# SKILL_SCRIPTS = $(dirname <path-to-this-SKILL.md>)/scripts
$SKILL_SCRIPTS/tmux-exec.sh "1.0" "ls -la"

Interactive Mode (-w PATTERN)

Sends keys and waits for a regex (e.g. a REPL prompt):

$SKILL_SCRIPTS/tmux-exec.sh -w '>>> ' "1.0" "print('hello')"

Options

Busy-pane protection

If a previous command is still running (e.g. after a timeout), the script detects this from its state file before proceeding:

• Command finished → state is cleared, new command proceeds.
• Command still running → error with command name, elapsed time, and recovery options.

2. Clear Stuck State (scripts/tmux-clear-state.sh)

Use when a pane's command was killed, OOM-ed, or hung and tmux-exec.sh refuses with "pane is busy" even though nothing is running.

# List all panes with recorded busy state (plus orphaned temp files)
$SKILL_SCRIPTS/tmux-clear-state.sh

# Clear state for a specific pane (current session)
$SKILL_SCRIPTS/tmux-clear-state.sh 1.0

# Clear state for a fully-qualified target
$SKILL_SCRIPTS/tmux-clear-state.sh myses:2.1

# Clear ALL stale state: dead panes + orphaned temp files
$SKILL_SCRIPTS/tmux-clear-state.sh --all

# Clear only orphaned out/ec temp files
$SKILL_SCRIPTS/tmux-clear-state.sh --orphans

# Dry-run: show what would be removed
$SKILL_SCRIPTS/tmux-clear-state.sh --dry-run --all

What it clears per pane:

• State file (<STATE_DIR>/<pane_num>) — the "busy" record
• Lock file (<STATE_DIR>/<pane_num>.lock) — the flock guard
• Temp files (out.*, ec.*) referenced in the state file

--all additionally removes orphaned out.*/ec.* files not referenced by any state.

3. Read (scripts/tmux-read.sh)

Read-only scrape of the last command's output. Warns if the pane is busy.

$SKILL_SCRIPTS/tmux-read.sh "1.0"

4. List (scripts/tmux-list.sh)

JSON inventory of all panes. Current session is listed first and marked. Shows "busy": true/false per pane with command and elapsed time.

$SKILL_SCRIPTS/tmux-list.sh

Use this to find idle panes before executing commands.

Interactive Tool Notes

Python REPL

Always set PYTHON_BASIC_REPL=1 — the fancy readline REPL breaks send-keys:

$SKILL_SCRIPTS/tmux-exec.sh "1.0" 'PYTHON_BASIC_REPL=1 python3 -q'
$SKILL_SCRIPTS/tmux-exec.sh -w '>>> ' "1.0" "print('hello')"

Debuggers

Default to lldb (unless user says gdb). Disable paging before sending commands.

Long output

Redirect to a file to avoid tmux scrollback limits:

$SKILL_SCRIPTS/tmux-exec.sh "1.0" 'long-command > /tmp/out.txt 2>&1'
$SKILL_SCRIPTS/tmux-exec.sh "1.0" 'cat /tmp/out.txt'

Error Handling

1. $SKILL_SCRIPTS/tmux-read.sh — inspect what's in the pane
2. $SKILL_SCRIPTS/tmux-list.sh — confirm target exists, check busy state
3. Test with echo test first
4. For complex issues read references/error-handling-and-debugging.md