Agent CLI observability & orchestration layer for tmux.

See which agents are working, waiting, idle, or blocked from your tmux status line, a live TUI, desktop notifications, and local reports.

English · 한국어

---

muxa is a small daemon and CLI for observing — and now driving — AI coding agents running inside terminal multiplexer panes. It reads agent state from existing hook/event systems (Claude Code, OpenAI Codex, Google Gemini CLI), falls back to screen-manifest detection for hook-less agents, and correlates it all with multiplexer panes and sessions. Through muxa mcp a coding agent can also orchestrate the others — inspect state, send prompts, wait for changes.

It does not fork the multiplexer or modify agent binaries. tmux and herdr are full backends and can be observed at the same time; zellij has a CLI baseline. See the Hosts table below.

Important

Beta. Event ingest, the daemon, CLI, live TUI, desktop notifications, stats, and reports work end-to-end, but APIs may still change before 1.0.

What You Get

Surface	What it does
muxa status-line	One-line tmux status-right summary for the active pane.
muxa watch	Full-screen TUI for agents and panes, with attach, prompt composition, and live previews.
muxa dashboard	Session-card TUI console for inspecting panes and sending prompts without attaching.
muxa attend	Jump to the agent blocked on input/choice/error longest.
muxa stats / muxa report	Local analytics for prompt history, agent state duration, tmux foreground time, and human thinking time.
muxa timeline	Full-screen TUI timeline of agent work, waiting, errors, human interaction, and tmux foreground time.
muxa activity	Raw duration ledger query for debugging exactly what fed stats/report.
BarShelf widget (macOS)	Menu-bar popover summary of active, working, waiting, and error agents.
Dashboard	Optional loopback HTTP UI with SSE live updates and a timeline graph.
Notifications	Optional desktop alerts when agents need attention.

Quick Start

Requires tmux 3.x (or herdr) and a Unix-like OS.

Homebrew (pre-built binaries, no Rust toolchain needed):

brew install open330/tap/muxa
muxa init

Or the one-shot installer (builds from source, requires Rust 1.88+):

curl -fsSL https://raw.githubusercontent.com/Open330/muxa/main/scripts/install.sh | sh

Or from source:

git clone https://github.com/Open330/muxa.git
cd muxa
cargo install --path crates/muxad --locked
cargo install --path crates/muxa-cli --locked
muxa init

Verify:

muxad &
muxa status
muxa watch

For install modes, muxa init presets, systemd, manual hook wiring, and rollback details, see docs/INSTALL.md.

Core Commands

Command	Purpose
muxa status [--json]	Human-readable table, or a versioned JSON snapshot for desktop integrations.
muxa watch [--view pane|session]	Live TUI picker/dashboard.
muxa dashboard [--since today]	Session-card TUI console with live capture, prompt composer, abort/terminate actions, and ACT/WACT totals.
muxa attend [--cycle] [--list]	Focus or list agents needing attention.
muxa status-line [--pane %N]	tmux status-line output.
muxa recap [--pane %N]	Recent prompts from retained disk history.
muxa stats --since today	Focused WACT/ACT/WORK/WAIT summary; group by day/project/agent/session. Add --graph for graph-only WACT over time or --verbose for diagnostic columns.
muxa report --since week	All breakdowns (day/project/agent/session) as focused ACT/WACT tables; add --json or --markdown to export.
muxa timeline --since today	Interactive session-grouped timeline; filter with --session main / --agent codex, sort with --sort waiting, or use --view heatmap.
muxa activity --type agent|tmux|human	Raw activity ledger intervals.
muxa sync	Backfill the registry by scanning tmux panes.
muxa register --name X [--pid N]	Surface an arbitrary background process (script, game, automation loop) as a pid-tracked row in muxa status.
muxa run --detach --name X -- <cmd>	Run a command in a muxa-owned PTY; it also appears in muxa status as a task.
muxa mcp	MCP stdio server so a coding agent can orchestrate muxa — inspect agents, send prompts, capture panes, wait for changes (claude mcp add muxa -- muxa mcp, see docs/MCP.md).
muxa init	Interactive install/uninstall wizard.
muxad	Daemon process.

Common stats queries:

muxa stats --since today --group-by session
muxa stats --since yesterday --group-by project
muxa report --since last-week
muxa timeline --since today --session main
muxa timeline --since today --exclude-session 'monitor*'
muxa stats --since month --exclude-pane '%42' --exclude-session 'monitor*'
muxa timeline --since today --group-by kind --sort waiting
muxa timeline --view heatmap --since 12w
muxa timeline --day 2026-06-06
muxa activity --since today --type human

--since accepts today, yesterday, week for a rolling 7-day window, month for a rolling 30-day window, last-week / "last week" for the previous Monday-Sunday calendar week, last-month / "last month" for the previous calendar month, rolling durations like 24h/7d/4w, local dates like 2026-06-06, RFC3339 timestamps, and all. See docs/ACTIVITY.md for ledger semantics, including HUMAN, THINK, and ACT.

muxa stats, muxa report, and muxa timeline also accept --exclude-pane and --exclude-session for long-lived monitoring scopes. Patterns are case-sensitive and support * and ?, e.g. --exclude-session 'monitor*'.

Supported Agents

Hook-based (authoritative). These wire into their existing hook/event systems, so muxa gets exact state transitions:

Agent	Status	Config
Claude Code	Supported	~/.claude/settings.json
OpenAI Codex	Supported	~/.codex/config.toml
Google Gemini CLI	Supported	~/.gemini/settings.json
opencode	Planned	tracking issue

Screen-detected (fallback). Agents with no hooks are classified from their pane contents via TOML manifests — bundled best-effort for cursor-agent, amp, copilot, aider, and goose, extensible per user. Hooks always win when present. See docs/SCREEN_DETECTION.md.

On herdr hosts, muxa additionally surfaces every agent herdr's own detection sees, with no manifest needed.

Hosts

muxa observes agents across terminal-multiplexer backends and can watch several at once (e.g. during a tmux→herdr migration):

Host	Status	Notes
tmux	Full	The default backend.
herdr	Full	Via herdr's socket API; see docs/HERDR.md.
zellij	CLI baseline	Richer plugin path planned; see docs/ZELLIJ.md.

See docs/MULTI_HOST.md for observing multiple hosts simultaneously.

More Docs

Topic	Doc
Install and wiring	docs/INSTALL.md
MCP control plane (muxa mcp)	docs/MCP.md
herdr host support	docs/HERDR.md
Multi-host observation	docs/MULTI_HOST.md
Screen-manifest detection	docs/SCREEN_DETECTION.md
Live TUI and prompt composer	docs/WATCH.md
CLI dashboard	docs/DASHBOARD_CLI.md
Stats, reports, activity ledger	docs/ACTIVITY.md
Timeline TUI and dashboard graph	docs/TIMELINE.md
Configuration reference	docs/CONFIGURATION.md
Web dashboard	docs/DASHBOARD.md
External sinks	docs/SINKS.md
Zellij plan	docs/ZELLIJ.md
Architecture and development	docs/ARCHITECTURE.md

Development

cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all -- --check

License

MIT OR Apache-2.0.