tmux-cli — Terminal Automation

tmux-cli is a command-line tool for controlling CLI applications running in tmux panes and windows. It automatically detects whether you are inside or outside tmux and uses the appropriate mode.

tmux-cli demo

What It Does

tmux-cli gives Claude Code (or any CLI agent) the ability to launch, send input to, capture output from, and kill programs running in tmux panes. This enables powerful multi-pane workflows where an agent can orchestrate several terminal applications simultaneously.

Auto-Detection

Inside tmux (Local Mode) — Manages panes in your current tmux window.
Outside tmux (Remote Mode) — Manages windows in a separate tmux session, creating it when launch first needs it. status and list commands do not create a session; full tmux targets can address existing panes without the managed session. Commands without a target use an active window from a successful managed launch.

Key Features

Launch shells and programs in new tmux panes
Send keystrokes (with configurable delay and auto-retry)
Capture pane output for inspection
Wait for a pane to become idle before proceeding
Execute a command and get its exit code as JSON
Interrupt (Ctrl+C) or send Escape to any pane
Safety guard: cannot kill your own pane

Quick Start

Always launch a shell first to prevent losing output when commands fail. In remote mode, launch returns a window target such as remote-cli-session:1; use the value it actually returns below:
Terminal window
```
tmux-cli launch "zsh"   # remote: window target; local: pane identifier
```
Run commands in the shell window (remote example):
Terminal window
```
tmux-cli send "pytest tests/" --pane=remote-cli-session:1
```

Wait and capture the result:

tmux-cli wait_idle --pane=remote-cli-session:1
tmux-cli capture --pane=remote-cli-session:1

Clean up when done:

tmux-cli kill --pane=remote-cli-session:1

Typical Workflow

# 1. Launch a shell (remote example; use the target actually returned)
tmux-cli launch "zsh"          # => window target, e.g. remote-cli-session:1

# 2. Run your command inside that shell
tmux-cli send "python script.py" --pane=remote-cli-session:1

# 3. Interact and inspect
tmux-cli send "some input" --pane=remote-cli-session:1
tmux-cli capture --pane=remote-cli-session:1

# 4. Clean up
tmux-cli kill --pane=remote-cli-session:1

Learn More

Command Reference — Full list of all tmux-cli commands and their options.
Resources — Curated links to articles, videos, and tools for advanced tmux + Claude Code integration.