ladderchaos/tmuxx

tmuxx

Use this skill to control tmux and worktree-based agent tasks through tmuxx agent.

Hard Rules

• Prefer tmuxx agent for session/window/worktree management. If pane command passthrough fails on a target environment, fall back to raw tmux send-keys for shell builtins.
• Always pass --json so outputs are machine-parseable.
• Prefer deterministic workflow commands over low-level primitives:
  • start-task
  • task-report
  • complete-task
  • abort-task
  • watch
  • supervise
• Only use low-level commands (split-pane, send-command, etc.) when workflow commands cannot solve the request.

Standard Workflow

1) Start task

tmuxx agent start-task <session_name> "<task prompt>" --json

Optional:

• --branch <name>
• --base-branch <branch>
• --agent-command "claude -p" (or other compatible command)

If --agent-command is omitted, tmuxx uses TMUXX_AGENT_COMMAND when set, otherwise claude -p in a normal terminal. Inside an existing agent session, you must pass --agent-command explicitly or set TMUXX_AGENT_COMMAND. tmuxx also rejects same-family nested launches like codex ... from Codex when it can detect the current runtime.

Setup Workspace (common first operation)

tmuxx agent create-session dev --json
tmuxx agent create-window dev --name editor --json
tmuxx agent create-window dev --name logs --json
tmuxx agent list-sessions --json

2) Monitor task — with pane-level insights

tmuxx agent task-report <branch> --json
tmuxx agent list-worktrees --json
tmuxx agent list-sessions --json
tmuxx agent watch --session <name> --event needs_prompt --json
tmuxx agent supervise --supervisor-pane <%id> --worker-session <name> --json

task-report now includes pane-level details for each task:

• pane_details[].status: "idle", "running", "waiting_for_input", "error"
• pane_details[].needs_prompt: True if pane is waiting for user input/approval (permission request, confirmation, etc.)
• pane_details[].window_name: Which window the pane is in
• pane_details[].command: What command is running

watch adds an event-driven waiting primitive on top of those signals:

• --event needs_prompt waits for approval/input walls
• --event completed waits for panes to be busy, then all return to idle
• --event attention waits for panes to need input or finish after they were busy
• --event text --pattern <regex> waits for output text to appear
• --notify triggers a desktop notification when matched
• --exec <command> runs a callback with TMUXX_WATCH_* environment variables
• --assume-busy lets completed/attention match the current terminal state immediately when a worker is already done or already blocked

supervise reuses those same worker filters/events and sends a structured handoff prompt into a supervisor pane instead of running a shell callback. Use it when one agent should wake and continue driving another blocked or recently finished worker.

list-sessions also includes pane-level statuses for every session, so you can see at a glance:

• Which panes are actively running
• Which are idle
• Which are waiting for user input (permission wall, approval prompt, etc.)

3) Complete task

tmuxx agent complete-task <branch> --test-command "<cmd>" --json

4) Abort task

tmuxx agent abort-task <branch> --json

Diagnostics / Inspection

tmuxx agent list-sessions --json
tmuxx agent status --json              # unified view of all running agents
tmuxx agent capture-pane %0 --lines 200 --json
tmuxx agent capture-window @0 --json
tmuxx agent read-agent-log <branch> --json
tmuxx agent watch --session claude --event needs_prompt --notify --json
tmuxx agent watch --branch <branch> --event attention --json
tmuxx agent watch --pane %0 --event attention --assume-busy --json
tmuxx agent watch --session claude --event text --pattern "Pushed" --exec "python3 watcher.py" --json
tmuxx agent supervise --supervisor-pane %9 --worker-session claude --goal "finish the task" --json

run-and-capture returns output scoped to the command you sent (not full pane history). status shows all worktree agents with branch, status, panes, and last output line.

Low-level Operations (Fallback)

tmuxx agent create-session <name> --json
tmuxx agent create-window <session> --name <name> --json
tmuxx agent split-pane %0 --horizontal --json
tmuxx agent send-command %0 --json -- <command text>
tmuxx agent send-text %0 --json -- <text>
tmuxx agent send-keys %0 C-c --json
tmuxx agent send-keys %0 --literal --json -- <text>
tmuxx agent run-and-capture %0 --wait-seconds 2 --lines 200 --json -- <command text>
tmuxx agent resize-pane %0 right --amount 10 --json
tmuxx agent kill-pane %0 --json
tmuxx agent kill-window @0 --json
tmuxx agent kill-session <name> --json

Deep Activity Insights (v0.3.7+)

tmuxx now tracks activities at the pane level to provide visibility into concurrent agent workflows (inspired by Superterm's "agentic attention" concept):

Pane Status Types

• idle: Pane is waiting at a shell prompt (bash, zsh, etc.)
• running: Pane has an active process (agent, compiler, test runner)
• waiting_for_input: Pane is expecting user input (permission request, confirmation, etc.)
• error: Pane process exited with error

Detecting "Needs Prompt"

The needs_prompt flag detects when a pane is blocked waiting for user action. Patterns detected:

• Permission requests: "permission needed", "Allow/Deny", etc.
• Input prompts: "[y/n]", "yes/no", "press any key"
• Approval walls: "waiting for approval", "confirm action"
• Tool prompts: "Tool: execute_bash" (Superterm-style)

Example Output

{
  "pane_details": [
    {
      "pane_id": "%0",
      "window_name": "editor",
      "command": "claude",
      "status": "running",
      "needs_prompt": false
    },
    {
      "pane_id": "%1",
      "window_name": "logs",
      "command": "tail",
      "status": "idle",
      "needs_prompt": false
    }
  ]
}

Use Cases

• Batch agent coordination: Launch 8 agents, check task-report to see which ones are blocked on permissions
• Deep session monitoring: list-sessions now shows pane statuses across all sessions — no more tab-cycling
• Prompt detection: Automatically identify when agents hit permission walls or need user approval
• Wake-up hooks: Use watch --notify or watch --exec to wake a human or another automation when a pane needs attention

Watch / Supervise Mode (v0.3.23+)

tmuxx agent watch turns tmuxx into a universal watcher for tmux-managed agent workflows. tmuxx agent supervise builds on top of the same event engine and sends a structured handoff prompt into a supervisor pane when a worker needs attention.

Events

• needs_prompt — match panes blocked on approval/input
• running — match active panes
• idle — match idle panes
• completed — wait until watched panes were busy and then all become idle
• attention — wait until watched panes were busy and then either need input or all become idle
• text — wait until recent_output matches --pattern

Filters

• --session <name|$id>
• --window <name|@id>
• --pane <%id>
• --branch <git-branch>

Callback / Handoff Behavior

When watch --exec is used, tmuxx exports:

• TMUXX_WATCH_EVENT
• TMUXX_WATCH_PAYLOAD
• TMUXX_WATCH_PANE_ID
• TMUXX_WATCH_WINDOW_ID
• TMUXX_WATCH_WINDOW_NAME
• TMUXX_WATCH_SESSION_ID
• TMUXX_WATCH_SESSION_NAME
• TMUXX_WATCH_BRANCH

Use --assume-busy with completed or attention when a worker is already sitting at the relevant terminal state and you want an immediate match.

When supervise is used, tmuxx sends a prompt containing:

• the triggering event
• worker filters
• matched pane ids / session / window / branch
• worker status and needs_prompt
• recent worker output
• optional original goal text

Examples

tmuxx agent watch --session claude --event needs_prompt --notify --json
tmuxx agent watch --branch feature-auth --event attention --json
tmuxx agent watch --pane %0 --event attention --assume-busy --json
tmuxx agent watch --session claude --event text --pattern "Pushed" --exec "python3 watcher.py" --json
tmuxx agent supervise --supervisor-pane %9 --worker-session claude --goal "finish the task" --json
tmuxx agent supervise --supervisor-pane %9 --worker-branch feature-auth --continuous --max-handoffs 2 --json

TUI Enhancements (v0.3.9+)

The interactive TUI (tmuxx) includes real-time pane activity visualization with ANSI color-rendered preview:

Header Legend

Single-line header with all status indicators:

[tmuxx]  ● active  ● selected  ● attached  ▶ running  ⏸ waiting  ⎇ worktree

Pane Status Badges

Each pane shows inline status in the tree:

• ▶ = running (blue) — agent actively executing
• ⏸ = waiting (red) — agent blocked on permission/approval

Worktree Tree Nodes (4th level)

Worktree info appears as a child node under panes (green ⎇ branch-name):

demo
├── editor :0 ●
│   └── zsh %0
├── build :1
│   ├── sleep %1 ▶
│   └── claude %2 ⏸
│       └── ⎇ feature-auth
└── logs :2
    └── tail %3 ▶

Key Improvements

• ANSI color preview — terminal output renders with full colors
• Context-aware footer — bindings hide when not applicable (e.g., Kill hidden with no sessions)
• Prompt detection — automatically flags agents waiting for user input
• Persistent theme (v0.3.11+) — theme selection saved to ~/.config/tmuxx/config.json and restored on launch
• Auto worktree detection (v0.3.12+) — any pane in a git worktree shows ⎇ branch automatically, regardless of how it was created
• Tmux status bar integration (v0.3.13+) — clickable ◀ BACK button in tmux status bar (top-left) to detach back to tmuxx TUI
• Search/filter (v0.3.18+) — press / to filter sessions/windows by name
• Send command (v0.3.18+) — press c to send a command to the selected pane without attaching
• Configurable refresh (v0.3.18+) — set refresh_interval in config.json (default 2.0s)
• XDG config (v0.3.18+) — respects $XDG_CONFIG_HOME for config path

Error Recovery

When a command fails:

1. Re-run with identical arguments once.
2. Run tmuxx agent task-report <branch> --json (if branch-based).
3. Run tmuxx agent list-sessions --json and tmuxx agent list-worktrees --json.
4. If still blocked, return the exact command, error text, and suggested next command.

Known Limitations

• For historical binaries (<=0.3.4), pane command passthrough may fail or require awkward quoting for shell builtins (cd, pwd, export).
• If stuck on an older binary, use raw tmux send-keys -t <pane> "<text>" Enter as a temporary fallback.

Notes

• screenshot-window may require optional dependencies (pip install "tmuxx[mcp]").
• If using npm, npm install -g tmuxx installs only a wrapper. The Python tmuxx binary must still be available in PATH (pipx install tmuxx recommended).
• Use direct tmux only if tmuxx is not installed or is broken, and explicitly state the reason.