muxboard

A tmux command center for AI agents, panes, and long-running terminal work.

muxboard is the calm "what needs me?" layer above your tmux sessions: scan the fleet, see which agents are stuck, jump to the right pane, reply, broadcast, or keep watching.

Try it

You need tmux on the machine where you run muxboard. Download release binaries for Linux and macOS from the latest release, or install from source:

cargo install --git https://github.com/aanari/muxboard --locked

Run it from any tmux pane:

muxboard

Not in tmux yet? Start tmux first, then run muxboard.

Why muxboard?

• See every tmux pane and agent in one scan-friendly board.
• Know which Codex, Claude Code, Opencode, or shell job needs attention.
• Jump, reply, broadcast, save fleets, and recover without losing tmux context.
• Stay local-first: no account, no cloud service, and no repo or worktree inspection.

Muxboard is tmux-native. It runs where tmux runs, so the same workflow works locally, over SSH, and on servers.

What you see first:

• Fleet: every pane, agent, and long-running job in one scan-friendly list.
• Details: the selected pane's state, blocker, action, and useful output.
• Output: a deeper, scrollable view when you ask for more.
• Footer: the next safe keys, always visible.

Power stays one layer down until you need it:

• send lists, named fleets, lane sends, and review-before-send broadcasts,
• tmux-native agent starts in the selected pane's directory,
• Browse for sessions and windows, Command Center for fleet triage,
• attention sorting, search, filters, muted alerts, desktop alerts, and terminal bell alerts,
• recent commands, macros, pane CPU/memory, and XDG-persisted state.

tmux plugin

Muxboard ships a TPM-compatible tmux plugin in this repo. Install the binary first, then add:

set -g @plugin 'aanari/muxboard'

Default key: prefix + M.

Useful presets:

• popup command center: quick overlay, leaves tmux layout untouched,
• dock: real tmux sidebar pane, best for long control sessions,
• drawer: temporary right-side overlay, closes cleanly after a jump,
• window: persistent control room.

See docs/tmux-plugin.md for plugin settings, dock/drawer behavior, status widgets, and advanced options.

Quick start

The default path is intentionally small:

• j / k to move,
• Enter to show the selected pane output while staying in muxboard,
• Esc to back out of Output, Send, Browse, Command Center, or focused Details,
• g to show the selected pane in tmux while leaving muxboard running,
• v to live-preview tmux panes as you move; Enter commits, Esc restores your original pane,
• Space to add or remove panes from the send list,
• : to type a command for the current send list,
• a to continue a waiting pane when muxboard offers that action,
• s to ask panes for one-line summaries,
• x to clear the send list,
• / to search,
• q to quit.

Send rules:

• nothing in the send list -> selected pane,
• one or more panes in the send list -> send list,
• review multi-target sends require Enter to confirm and Esc to cancel.

Need more? Press .. More keeps advanced actions in context: Browse, Command Center, start agent, fleets, lane send, pane CPU/memory, alerts, filters, notifications, and pane sends.

Secondary keys:

• Tab switches focus between Fleet and Details when both surfaces are active,
• L cycles layout: auto, side by side, stacked,
• r refreshes,
• on the Send surface, ] repeats the most recent command to the current send destination,
• on the Send surface, p then a macro key pins the most recent command into a macro slot, default 1-5,
• on the Send surface, a macro key replays a saved macro slot, default 1-5,
• Esc backs out of active inputs and overlays.

Common More-menu keys, after pressing .. Labels adapt to the current surface:

• Enter shows output, returns to details, or opens a Browse window,
• [ browses tmux sessions and windows,
• ] shows Command Center,
• c mute selected alert,
• w unmute selected alert,
• a mute all alerts,
• u unmute all alerts,
• i continue waiting panes,
• e send Enter to the selected pane,
• y send y + Enter,
• n send n + Enter,
• z zoom the selected pane,
• + start a new agent in the selected pane's directory,
• t change sort order,
• f change visible panes,
• g save a fleet,
• l choose a saved fleet,
• d delete the selected saved fleet,
• b send to the selected lane,
• m toggle pane CPU/memory,
• o toggle desktop notifications,
• v toggle terminal bell,
• h cycle alert repeat delay,
• p cycle alert types.

Commands and macros support placeholders: {session}, {window}, {path}, {id}, {cmd}, {title}, and {lane}.

Config and state

Muxboard uses XDG-style paths by default:

• config: ~/.config/muxboard/config.json
• state: ~/.local/state/muxboard/state.json

By default, muxboard uses Auto: it inspects live tmux theme options, matches known safe themes when RGB is available, and falls back to System Colors. Use muxboard --theme-picker to choose manually, or script a dotfile choice with:

muxboard --theme auto
muxboard --theme system
# Same native-color preset, if that wording is clearer:
muxboard --theme terminal-colors

Create a full editable config from the generated defaults:

config_dir="${XDG_CONFIG_HOME:-$HOME/.config}/muxboard"
mkdir -p "$config_dir"
muxboard --print-config-example > "$config_dir/config.json"

Useful config fields:

• layout_preset supports Auto, Horizontal, and Vertical.
• ui_settings.theme.preset supports Auto, Calm, Contrast, Mono, TerminalNative, CatppuccinLatte, CatppuccinMocha, TokyoNight, GruvboxDark, GruvboxLight, Nord, and RosePine.
• Kebab-case aliases like auto, match-tmux, light, dark, system, system-colors, terminal-colors, native-colors, catppuccin-light, catppuccin-mocha, tokyo-night, gruvbox, rose-pine, terminal, ansi, and no-color also work.
• Named themes are semantic mappings into muxboard's slots; use System Colors, stored as TerminalNative, to follow your terminal palette.
• Auto matching reads live tmux options, not terminal config files. Explicit theme config still wins.
• The older theme_preset field still works for existing configs.
• Set ui_settings.theme.overrides for small custom touches, for example "accent": "#4078F2", "warning": "#fc0", or "surface": "24".

To print ready-to-copy defaults:

muxboard --print-config-example
muxboard --print-default-keybindings

SSH and local behavior

Desktop notification behavior:

• local GUI session: desktop notification plus terminal bell,
• SSH session: terminal bell and in-dashboard alerts only, no GUI notification attempts.

Terminal behavior:

• UTF-8 terminals get the normal clean bordered UI,
• TERM=dumb, non-UTF-8 locales, or NO_COLOR fall back to ASCII borders and plain styling.

Pane CPU/memory is host-local. It shows CPU and memory for each tmux pane PID on the host where muxboard is running. If a pane is an ssh client into another machine, the values reflect that local ssh process, not the remote workload behind it.

Structured fleet reports are host-agnostic. If an agent replies with STATUS=... | BLOCKER=... | NEXT=..., or emits a heartbeat like muxboard: status=...; blocker=...; next=..., muxboard will parse and surface that state in Fleet and Details.

Muxboard also reads conservative local status hints from recent Codex and Claude Code transcripts when they map cleanly to an obvious matching tmux pane. It uses that native signal for state, thread title, and review attention, while explicit tmux bridge hooks still take priority.

Demo media

The animation above is synthetic and safe to share. To record your own GIF, MP4, or asciinema cast from the same private demo harness, see docs/demo.md.

Product scope

V1 is intentionally tmux-first and agent-control-first. It does not inspect repos, branches, or worktrees; fleet control works the same for local panes, SSH panes, and generic long-running terminal jobs. VCS context belongs in V2 as an optional project layer, not as a dependency for the core dashboard.

Contributing

Contributor workflow, verification commands, release checks, coverage, and probe/debug notes live in CONTRIBUTING.md.

License

Licensed under Apache-2.0. See LICENSE-APACHE.