tmuxx 0.4.1

TUI for humans. Deterministic agent CLI for AI workflows. One interface to see, control, and automate tmux.

tmuxx

Your terminal, orchestrated. By you and your agents.

  _|
_|_|_|_|  _|_|_|  _|_|    _|    _|  _|    _|  _|    _|
  _|      _|    _|    _|  _|    _|    _|_|      _|_|
  _|      _|    _|    _|  _|    _|  _|    _|  _|    _|
    _|_|  _|    _|    _|    _|_|_|  _|    _|  _|    _|

TUI for humans. Deterministic agent CLI for AI workflows. One interface to see, control, and automate tmux.

Install

pip install tmuxx
# on Debian/Ubuntu or other externally-managed Python systems:
pipx install tmuxx
# optional Node wrapper (expects tmuxx binary in PATH):
npm install -g tmuxx

Requires Python 3.10+ and tmux. The npm package is a thin wrapper that forwards to the tmuxx binary.

On Debian/Ubuntu, plain pip install tmuxx may fail with an externally-managed-environment error (PEP 668). Use pipx install tmuxx instead, or install inside a virtual environment with python3 -m venv .venv.

Truecolor support: If colors look off on your VM or remote server, enable truecolor:

echo 'export COLORTERM=truecolor' >> ~/.bashrc

Usage

# default: interactive TUI with pane activity indicators
tmuxx

# explicit TUI mode
tmuxx tui

# deterministic agent automation mode
tmuxx agent --help

# binary version
tmuxx --version

TUI Features

The interactive TUI is a click-first cockpit with three rows inside a single rounded frame:

• Sessions — pills for every tmux session. Actions: + Session, Rename, Attach, Kill.
• Windows — cards for every window across every session, prefixed <session>/<idx> <name>. Click switches both session and window. Actions: + Window, Rename, Attach, Kill.
• Panes — chips for every pane across every window, prefixed <window>/<id> <command>. Click switches the preview to that pane. Actions: + Pane H, + Pane V, Send Msg, Attach, Kill.

The preview body below the cockpit renders the selected pane / window grid / session summary with full ANSI colors.

Status glyphs only fire when something needs your attention:

• ◉ (amber, blinking) — pane is waiting for input (y/n prompt, agent permission wall, "press enter to continue", …).
• ⠋⠹⠸… (cyan, animated) — pane is agent thinking (claude / codex / gemini running).
• (no glyph) — idle or plain running shell.

Worktree branch auto-detected per pane — windows whose pane sits in a git worktree show ⎇ branch in the card subtitle.

Footer carries Home, Refresh, Search (filters windows + panes by name / command / branch), Copy (preview to clipboard), Skill (CLI surface reference), Help.

After attaching to a session, click BACK in the tmux status bar (top-left) to detach back to the TUI.

Keybindings

Key	Action
q	Quit
?	Show help / keymap reference
Ctrl+P	Command palette (Textual built-in)
Esc	Dismiss any modal
Enter	Submit modal input

Most navigation is click-driven; clicking session pills, window cards, and pane chips switches the selected scope and updates the preview without keyboard shortcuts.

Agent Orchestration

Run parallel AI agents in isolated git worktrees, each with its own branch and tmux window. Monitor all agents with pane-level activity visibility — see which ones are running, idle, or blocked on user input.

Deterministic Workflow Commands

tmuxx agent start-task <session_name> "<prompt>" [--branch ...] [--base-branch ...] [--agent-command ...]
tmuxx agent task-report <branch>
tmuxx agent complete-task <branch> [--test-command ...] [--commit-message ...]
tmuxx agent abort-task <branch>
tmuxx agent status
tmuxx agent watch [--event needs_prompt|running|idle|completed|attention|text] [--session ...]
tmuxx agent supervise --supervisor-pane <%id> [--worker-session ...] [--goal ...]

Recommended command flow for skills:

1. start-task creates worktree + tmux window and runs the agent command.
2. task-report provides branch status, diff, and log presence with stable fields.
3. complete-task or abort-task performs capture + cleanup in one operation.

If you omit --agent-command, tmuxx uses TMUXX_AGENT_COMMAND when set, otherwise it falls back to claude -p in a normal terminal. Inside an existing agent session, tmuxx refuses to guess a default and requires an explicit override. It also rejects same-family nested launches such as codex ... from Codex or claude ... from Claude when it can detect the active runtime. Activating from the TUI now always switches to the target window first, then focuses the selected pane (or that window's active pane).

Watch or supervise workers

watch gives tmuxx a native hook-like primitive for machine-level automation. It polls tmux state until a condition matches, then returns JSON, optionally shows a desktop notification, and can execute a callback. supervise builds on the same signals, but instead of running an external callback it sends a structured handoff prompt into a supervisor pane.

# wake up when any pane in the Claude session needs user input
tmuxx agent watch --session claude --event needs_prompt --json

# wait until a task pane becomes attention-worthy (needs input or finishes)
tmuxx agent watch --branch feat-auth-tests --event attention --notify --json

# treat the current worker as already busy so attention can match its current prompt/idle state
tmuxx agent watch --pane %0 --event attention --assume-busy --json

# trigger on matched output text and run a callback with TMUXX_WATCH_* env vars
tmuxx agent watch --session claude --event text --pattern "Pushed" \
  --exec 'python3 watcher.py' --json

# send a supervision handoff to a supervisor pane
tmuxx agent supervise --supervisor-pane %9 --worker-session claude \
  --goal "finish the task" --json

# keep re-arming supervision for repeated worker interruptions
tmuxx agent supervise --supervisor-pane %9 --worker-branch feat-auth-tests \
  --continuous --max-handoffs 2 --json

Available watch events:

• needs_prompt — a pane is waiting for approval/input
• running — a pane is actively running
• idle — a pane is idle at the shell
• completed — watched panes were busy and then all became idle
• attention — watched panes were busy and then either need input or all become idle
• text — pane output matches --pattern

Use --assume-busy with completed or attention when you want tmuxx to treat the current pane state as post-busy immediately (useful for already-finished or already-blocked agent sessions).

When --exec is used, tmuxx exports these environment variables to the callback:

• 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

JSON-first Mode

All tmuxx agent commands support --json for machine-safe parsing:

tmuxx agent list-worktrees --json
tmuxx agent start-task dev "fix login bug" --json
TMUXX_AGENT_COMMAND="gemini -p" tmuxx agent start-task dev "fix login bug" --json
tmuxx agent task-report fix-login-bug --json
tmuxx agent complete-task fix-login-bug --test-command "pytest -q" --json
tmuxx agent status --json
tmuxx agent watch --session claude --event needs_prompt --json
tmuxx agent supervise --supervisor-pane %9 --worker-session claude --json

Configuration

Create ~/.config/tmuxx/config.json (or $XDG_CONFIG_HOME/tmuxx/config.json):

{
  "theme": "textual-dark",
  "refresh_interval": 2.0
}

run-and-capture is scoped to the command you send (it returns command-local output, not full pane scrollback).

Full Command Surface

# introspection
tmuxx agent list-sessions
tmuxx agent capture-pane %1 --lines 200
tmuxx agent capture-window @2
tmuxx agent screenshot-window @2 --output ./window.png

# session/window/pane operations
tmuxx agent create-session dev
tmuxx agent create-window dev --name logs
tmuxx agent split-pane %3 --horizontal
tmuxx agent send-command %3 -- npm test
tmuxx agent send-text %3 -- "draft note in shell"
tmuxx agent send-keys %3 C-c
tmuxx agent send-keys %3 --literal -- "echo hello"
tmuxx agent run-and-capture %3 --wait-seconds 2 --lines 300 -- pytest -q

# worktree operations
tmuxx agent launch-agent dev "add auth tests" --base-branch feat-auth
tmuxx agent list-worktrees
tmuxx agent diff-worktree feat-auth-tests
tmuxx agent merge-worktree feat-auth-tests --test-command "pytest -q"
tmuxx agent discard-worktree feat-auth-tests
tmuxx agent read-agent-log feat-auth-tests

# watcher / notification primitives
tmuxx agent watch --session claude --event needs_prompt --notify
tmuxx agent watch --branch feat-auth-tests --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'
tmuxx agent supervise --supervisor-pane %9 --worker-session claude --goal "finish the task"
tmuxx agent supervise --supervisor-pane %9 --worker-branch feat-auth-tests --continuous --max-handoffs 2 --json

Legacy MCP Compatibility (Optional)

tmuxx is now single-binary first. If you still need MCP for external clients, the legacy module remains in source.

pip install "tmuxx[mcp]"
python tmux_mcp.py

License

MIT