UserAd TMUX Orchestration
Setup
Before any tmux operation:
- Get binary path:
which tmux→ store as{{TMUX}} - Get session:
{{TMUX}} display-message -p '#S'→ store as{{SESSION}}
Helper Scripts
Primary method for tmux operations. Located in scripts/ directory.
| Script | Usage | Description |
|---|---|---|
spawn_subagent.sh |
<window-name> [command] |
Spawn a subagent in a new window. Default: claude --dangerously-skip-permissions |
send_command.sh |
<window-name> <command> |
Send text to window, wait 1s, execute with Enter |
exit_subagent.sh |
<window-name> |
Send /exit, wait 1s, kill window if still present |
Run from skill directory: ./scripts/<script-name>.sh
All scripts output "Done" on success or an error message on failure.
Subagent Workflow
.claude/skills/tmux/scripts/spawn_subagent.sh agent-task-1 "claude --agent researcher --dangerously-skip-permissions".claude/skills/tmux/scripts/send_command.sh agent-task-1 "Research X and write to /tmp/output.md"- Await notification via agentmail or display-message (do not poll)
- Read output file
.claude/skills/tmux/scripts/exit_subagent.sh agent-task-1
When subagent completes: {{TMUX}} display-message -d 5000 "{{WINDOW}}: {{MESSAGE}}"
Mandatory Requirements
- The agent shall use tmux windows exclusively (not panes).
- The agent shall use unique window names following
agent-{task}-{number}pattern. - The agent shall await subagent notifications via agentmail or display-message (no polling).
- When spawning a subagent, the agent shall use
spawn_subagent.sh. - When sending commands to a window, the agent shall use
send_command.sh. - When stopping a subagent, the agent shall use
exit_subagent.sh.
Commands Reference
Raw tmux commands for debugging or edge cases. Use Helper Scripts for standard operations.
| Action | Command |
|---|---|
| List windows | {{TMUX}} list-windows -t "{{SESSION}}" -F "#{window_name}" |
| New window | {{TMUX}} new-window -d -t "{{SESSION}}" -n "{{NAME}}" "{{COMMAND}}" |
| Send text | {{TMUX}} send-keys -t "{{SESSION}}:{{NAME}}" -l "{{TEXT}}" |
| Send enter | {{TMUX}} send-keys -t "{{SESSION}}:{{NAME}}" Enter |
| Stop command | {{TMUX}} send-keys -t "{{SESSION}}:{{NAME}}" C-c |
| Close window | {{TMUX}} kill-window -t "{{SESSION}}:{{NAME}}" |
| Get content | {{TMUX}} capture-pane -t "{{SESSION}}:{{NAME}}" -p | tail -100 |
| Show message | {{TMUX}} display-message -d 2000 "{{MESSAGE}}" |
Common Agent Commands
Commands to send to Claude subagents:
| Command | Description |
|---|---|
/exit |
Exit the agent gracefully |
/clear |
Clear the agent's context window |
/compact handoff:<info> |
Compact context, preserving specified handoff info |
Example handoff: /compact handoff:Focus on task-XXX and task-YYY