tmai 0.12.0

Tmux Multi Agent Interface - Monitor and control AI agents in tmux
Documentation

tmai

Tmux Multi Agent Interface - Monitor and control multiple AI agents running in tmux.

Rust License

tmai demo

Features

  • Multi-agent monitoring - Track multiple AI coding agents (Claude Code, OpenCode, etc.) across tmux panes
  • Single-pane operation - Approve without attaching to agent panes
  • Real-time preview - See agent output without switching panes (with ANSI color support)
  • Quick approval - Approve tool calls with single keystroke (y)
  • AskUserQuestion support - Respond to agent questions with number selection
  • Passthrough mode - Send keys directly to the agent pane
  • Status detection - Automatic detection of idle, processing, and awaiting approval states
  • Claude Code Hooks - Event-driven state detection via HTTP hooks (tmai init)
  • PTY wrapping - High-precision state detection via PTY proxy for real-time I/O monitoring
  • Exfil detection - Security monitoring for external data transmission
  • Web Remote Control - Control agents from your smartphone via QR code
  • Agent Teams - Visualize Claude Code Agent Teams structure and task progress
  • Mode detection - Detect Plan/Delegate/Auto-approve modes from terminal title icons
  • Auto-approve - Automatic approval of safe actions with 4 modes: Rules (instant), AI, Hybrid, or Off
  • Usage monitoring - Check Claude subscription usage (5h session / weekly limits) with U key

Documentation

For detailed guides and workflows, see doc/:

Installation

cargo install tmai

Or build from source:

git clone https://github.com/trust-delta/tmai
cd tmai
cargo build --release

Quick Start

1. Set up hooks (recommended, one-time)

tmai init

This configures Claude Code to send real-time events to tmai for high-precision state detection.

2. Run tmai

Start tmai in a tmux session:

tmai

Configuration

Create a config file in one of these locations (first found wins):

  • ~/.config/tmai/config.toml
  • ~/.tmai.toml

Example:

poll_interval_ms = 500
passthrough_poll_interval_ms = 10
capture_lines = 100
attached_only = true

[ui]
show_preview = true
preview_height = 40
color = true

[teams]
enabled = true
scan_interval = 5

[usage]
auto_refresh_min = 15  # 0 = manual only (default)

[auto_approve]
enabled = true
model = "haiku"

Keybindings

Key Action
j / k Navigate agents
y Approve / select Yes
n Select No (UserQuestion)
1-9 Select option by number
Space Toggle (multi-select)
i Enter input mode
→ Enter passthrough mode
t Task overlay (team member selected)
T Team overview
W Restart as IPC-wrapped (non-IPC Claude Code)
U Fetch subscription usage (Claude Max/Pro)
Esc Exit mode / Quit
? Help

Modes

  • Normal mode - Navigate and quick actions
  • Input mode (i) - Type text to send to agent
  • Passthrough mode (→) - Keys sent directly to pane

PTY Wrapping (Optional)

For additional features like exfil detection and full AskUserQuestion parsing, wrap AI agents with a PTY proxy:

# Start Claude Code with PTY wrapping
tmai wrap claude

# With arguments
tmai wrap claude --dangerously-skip-permissions

# Other agents
tmai wrap codex
tmai wrap gemini

Additional benefits (on top of hooks):

  • Exfil detection - Monitor external data transmission
  • Full AskUserQuestion parsing - Parse option text for direct selection
  • Real-time I/O monitoring - Direct I/O stream analysis

When creating new AI processes from tmai UI, they are automatically wrapped.

Web Remote Control

Control your AI agents from your smartphone:

  1. Press r to display QR code
  2. Scan with your phone
  3. Approve or select options from the web interface
# config.toml
[web]
enabled = true
port = 9876

WSL2 Setup

For WSL2 with mirrored networking mode, allow the port through Windows Firewall:

# Run as Administrator
New-NetFirewallRule -DisplayName "tmai Web Remote" -Direction Inbound -Protocol TCP -LocalPort 9876 -Action Allow

NAT mode (legacy)

If you are not using mirrored mode, port forwarding is required:

# Run as Administrator
.\scripts\setup-wsl-portforward.ps1

# To remove
.\scripts\setup-wsl-portforward.ps1 -Remove

Note: In NAT mode, the WSL IP address changes on reboot. Re-run the script if the connection stops working.

Supported Agents

Agent Detection Hooks PTY Wrap
Claude Code ✅ Supported ✅ ✅
OpenCode ✅ Supported — ✅
Codex CLI ✅ Supported — ✅
Gemini CLI ✅ Supported — ✅

Usage Monitoring

Press U to check your Claude subscription usage (session / weekly limits). tmai spawns a temporary Claude Code instance in the background, runs /usage, and displays the results.

Screenshots

┌─────────────────┬─────────────────────────────────┐
│ Sessions        │ Preview                         │
│                 │                                 │
│ [◈Hook] main:0  │ Do you want to make this edit?  │
│   Claude Code   │                                 │
│   ⠋ Processing  │ ❯ 1. Yes                        │
│                 │   2. Yes, allow all...          │
│ [IPC] main:0.1  │   3. No                         │
│   Claude Code   │                                 │
│   ✳ Idle        │                                 │
└─────────────────┴─────────────────────────────────┘
 j/k:Nav 1-9:Select i:Input →:Direct ?:Help q:Quit

Acknowledgments

Inspired by tmuxcc.

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT