muxa

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 26 Open GitHub ↗

Agent CLI observability and orchestration layer for tmux

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

**Work-oriented AI-agent observability & orchestration for tmux.**

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

[![CI](https://github.com/Open330/muxa/actions/workflows/ci.yml/badge.svg)](https://github.com/Open330/muxa/actions/workflows/ci.yml)
![MSRV](https://img.shields.io/badge/MSRV-1.88-informational)
![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue)
![status](https://img.shields.io/badge/status-beta-yellow)

**English** · [한국어](README.ko.md)

</div>

---

## Try Muxa onboarding before reading

Launch the complete fullscreen tour—no Muxa binary download or installation:

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

<div align="center">
  <img src="docs/demo.gif" alt="muxa watch: sixteen agent sessions on one screen, the inspector, the swarm view, and muxa attend jumping to the agent that needs you" width="900" />
  <br />
  <sub><code>muxa watch</code> — the fleet, the inspector, the swarm view, and <code>muxa attend</code>.</sub>
</div>

`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,
[rmux](https://rmux.io), and [herdr](https://herdr.dev) can be observed at the
same time; zellij has a CLI baseline. See the Hosts table below.

## Optimized for work-oriented tmux

Muxa treats tmux as a durable work execution model, not just a collection of
terminal panes:

| tmux object | Muxa meaning | How it is used |
| --- | --- | --- |
| **session** | One workspace or project | Durable project context containing several independent work windows. |
| **window** | One work item or ticket | Stable work identity and cwd. Starting the same work again reuses this window. |
| **pane** | One agent | An implementer, reviewer, or helper working inside that work window. |

The intended workflow is equally direct:

1. Start a work ID once; Muxa creates or reuses the workspace session, creates
   its work window, and starts the first agent pane.
2. Add implementer, reviewer, or helper agents as additional panes in that
   same work window. Other tickets become sibling windows.
3. Observe, preview, message, and control those agents through `muxa watch`,
   or let an agent use the same policy through `muxa mcp`.
4. Close an agent pane, work window, or whole workspace session explicitly.
   Muxa refuses to terminate unmanaged tmux objects.

In short: **workspace/session → work/window → agent/pane → observe and
collaborate → explicit close**. Run `muxa onboard` for one continuous safe scenario.
It welcomes you with the reason for creating a practice tmux session, then lets
you type `tmux new-session`, learn the hierarchy, windows, panes, detach/attach,
and managed prefix bindings before continuing directly into the Muxa watch workflow.
Nothing in the tour mutates a live tmux session.

> [!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 peek` | `prefix + q` overlay: each pane's live screen dimmed under a box with its agent's state, summary, and latest prompt/response — including how long ago you last prompted it and which pane was prompted most recently; press a digit to jump. |
| `muxa watch` | Main TUI for agents, prompts, live previews, and same-window collaboration. |
| `muxa dashboard` | Workspace-card TUI console for pane operations and authenticated same-work agent collaboration. |
| `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. |

## Install Muxa

If you decide to keep Muxa, install it with one of the following methods.

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

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

```bash
brew install open330/tap/muxa
muxa init
```

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

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

Or from source:

```bash
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:

```bash
muxad &
muxa status
muxa watch
```

### Collaborate from `muxa watch`

<div align="center">
  <img src="docs/demo-collab.gif" alt="muxa watch: the collaboration mailbox, messaging the session under the cursor, and asking claude a headless question" width="900" />
  <br />
  <sub><code>b</code> mailbox · <code>m</code> message the row under the cursor · <code>a</code>/<code>A</code> headless ask.</sub>
</div>

The model is simple: **one tmux window is one room**. Interactive watch and
dashboard messages are sent by the operator console, so either popup can be
opened from an agent or a spare shell pane. Agent-initiated MCP and `muxa msg`
requests still use that agent's pane identity.

One-time setup: add the following to `~/.config/muxa/config.toml`, restart
`muxad`, and run `muxa init` to install the `prefix+s` watch popup.

```toml
[collaboration]
enabled = true
wake = "idle_only"
```

Register the MCP server once for both agent hosts, then restart agents that
were already running so they can read and reply to requests themselves.

```bash
claude mcp add --scope user muxa -- muxa mcp
codex mcp add muxa -- muxa mcp
```

Codex only forwards explicitly allowed environment variables to stdio MCP
servers. Add this line to the generated `[mcp_servers.muxa]` table in
`~/.codex/config.toml` (especially when using a custom muxa/tmux socket):

```toml
env_vars = ["RMUX", "RMUX_PANE", "TMUX", "TMUX_PANE", "MUXA_SOCKET"]
```

Muxa also recovers the pane from process ancestry across active pane backends
for existing default-endpoint Codex registrations, so older setups fail safely
rather than appearing paneless.

Connected agents are told that room peers can serve as read-only reviewers or
narrowly scoped execution subagents. Requests and replies can also carry
validated AIR 1.0 artifact references, which watch visualizes with
profile-colored mailbox badges.

Agents reported as synthetic by `muxa doctor` are omitted from collaboration
until a hook event establishes a stable session identity. Submit a prompt or
restart that agent, then check again.

Then:

1. Run two agents in two panes of the same tmux window.
2. Press `prefix+s` from any pane and select the recipient's session, window,
   or pane. Parent rows resolve to the lowest numeric live agent and show the
   exact target in the composer title.
3. Press `m`, type the request, and press `Enter`. At any point in the draft,
   `/` opens reusable skills registered with `muxa skill add`; selection inserts
   at the cursor and a second `Enter` sends. Press `M` to read and reply from
   the mailbox (`b` remains an alias).

For request/reply details, see
[docs/COLLABORATION.md](docs/COLLABORATION.md); for skill registration and
composer controls, see [docs/WATCH.md](docs/WATCH.md).

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

## Core Commands

Managed tmux policy: one session is a workspace/project, each window is a
work/ticket, and each pane is an agent. `muxa onboard` teaches tmux first and
introduces this Muxa mapping only after the tmux exercises, as one
continuous scenario. It starts at a blank virtual shell, accepts the real
`tmux new-session -s muxa-onboarding` and `tmux attach -t muxa-onboarding`
commands, and explains why each session command is needed before asking for it.
It preserves every virtual window/pane transition, then continues without
leaving fullscreen into the current `muxa watch` workflow. The watch half mirrors
the left-edge session-state gutter, columns, 50/50 inspector, overlays, and
footer. Commands and keys that you must enter are shown in bold yellow in both
the dialog body and footer. You advance with the real `j`, `l`, `Alt-T`, `o`,
`?`, `n`, `m`,
`Backspace`, `M`, and `q` actions. One 20-step counter covers the whole scenario:
managed prefix bindings are step 11 and work navigation follows as step 12.
Korean is selected automatically for a Korean locale, can be requested with
`--lang ko`, and can be toggled with `F2` during the tour.

<div align="center">
  <img src="docs/demo-onboard.gif" alt="Unified Korean onboarding: virtual shell and tmux practice flowing directly into the Muxa watch workflow" width="900" />
  <br />
  <sub><code>muxa onboard</code> — shell, tmux, and Muxa in one safe interactive scenario.</sub>
</div>

| Command | Purpose |
| --- | --- |
| `muxa status [--json]` | Human-readable table, or a versioned JSON snapshot for desktop integrations. |
| `muxa watch [--view pane\|work]` | Live workspace → work → agent TUI picker/dashboard. |
| `muxa dashboard [--since today]` | Workspace-card TUI with live capture, prompt/actions, ACT/WACT totals, and collaboration mailbox controls. |
| `muxa attend [--cycle] [--list]` | Focus or list agents needing attention. |
| `muxa status-line [--pane %N]` | tmux status-line output. |
| `muxa peek [--plain]` | Per-pane overlay for the current tmux window; `--plain` prints it as text. |
| `muxa recap [--pane %N]` | Recent prompts from retained disk history. |
| `muxa peers` / `muxa identity` / `muxa msg` | Discover and name same-window agents, then exchange durable request/reply messages. |
| `muxa skill add/list/show/remove` | Manage reusable `/` prompt templates for watch/dashboard messages and watch ask. |
| `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 active pane hosts. |
| `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 work start muxa-onboarding --workspace muxa --agent codex ...` | Create/reuse workspace session `muxa`, create/reuse its work window, and add an agent pane. |
| `muxa workspace list/show/close` | Inspect or explicitly close workspace/project sessions. |
| `muxa work list/show/close [--workspace muxa]` | Inspect or explicitly close work/ticket windows. |
| `muxa agent start --workspace muxa --work muxa-onboarding ...` | Add an allowlisted agent pane to one work window; also exposed as MCP `muxa_start_agent`. |
| `muxa agent control --pane %N --action interrupt` | Interrupt or explicitly terminate one managed agent pane. |
| `muxa onboard [--lang auto\|en\|ko]` | Unified shell → tmux → Muxa fullscreen walkthrough. `F2` switches language, `--no-quiz` skips gates, and `--print` emits the combined guide. |
| `muxa mcp` | MCP stdio server so a coding agent can orchestrate muxa — inspect agents, send prompts, capture panes, wait for changes (`claude mcp add --scope user muxa -- muxa mcp`, see [docs/MCP.md](docs/MCP.md)). |
| `muxa init` | Interactive install/uninstall wizard. |
| `muxad` | Daemon process. |

Common stats queries:

```bash
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](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](https://github.com/Open330/muxa/issues/14) |

**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](docs/SCREEN_DETECTION.md).

On [herdr](https://herdr.dev) 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. |
| [rmux](https://rmux.io) | Initial CLI backend | Pane discovery, capture, focus, and targeted input; see [docs/RMUX.md](docs/RMUX.md). |
| [herdr](https://herdr.dev) | Full | Via herdr's socket API; see [docs/HERDR.md](docs/HERDR.md). |
| zellij | CLI baseline | Richer plugin path planned; see [docs/ZELLIJ.md](docs/ZELLIJ.md). |

See [docs/MULTI_HOST.md](docs/MULTI_HOST.md) for observing multiple hosts
simultaneously.

## More Docs

| Topic | Doc |
| --- | --- |
| Install and wiring | [docs/INSTALL.md](docs/INSTALL.md) |
| Onboarding and work/agent policy (한국어) | [docs/ONBOARDING.ko.md](docs/ONBOARDING.ko.md) |
| MCP control plane (`muxa mcp`) | [docs/MCP.md](docs/MCP.md) |
| herdr host support | [docs/HERDR.md](docs/HERDR.md) |
| rmux host support | [docs/RMUX.md](docs/RMUX.md) |
| Multi-host observation | [docs/MULTI_HOST.md](docs/MULTI_HOST.md) |
| Screen-manifest detection | [docs/SCREEN_DETECTION.md](docs/SCREEN_DETECTION.md) |
| Live TUI and prompt composer | [docs/WATCH.md](docs/WATCH.md) |
| CLI dashboard | [docs/DASHBOARD_CLI.md](docs/DASHBOARD_CLI.md) |
| Stats, reports, activity ledger | [docs/ACTIVITY.md](docs/ACTIVITY.md) |
| Timeline TUI and dashboard graph | [docs/TIMELINE.md](docs/TIMELINE.md) |
| Configuration reference | [docs/CONFIGURATION.md](docs/CONFIGURATION.md) |
| Web dashboard | [docs/DASHBOARD.md](docs/DASHBOARD.md) |
| External sinks | [docs/SINKS.md](docs/SINKS.md) |
| Zellij plan | [docs/ZELLIJ.md](docs/ZELLIJ.md) |
| Architecture and development | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
| Agent collaboration | [docs/COLLABORATION.md](docs/COLLABORATION.md) |

## Development

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

## License

MIT OR Apache-2.0.

muxa

Today's picks

Was this content helpful?

Recent Feedback

muxa

Today's picks

Was this content helpful?

Recent Feedback

Download README