cmux-team

cmux-team

Multi-agent development orchestration with Claude Code + cmux.

日本語版 README はこちら

Demo

https://github.com/user-attachments/assets/1d402a69-f48c-4a43-b52d-9c80f0f90ea1

Why cmux-team?

Claude Code's built-in sub-agents are useful, but you can't see what they're doing. You only get the final result — the process is a black box.

This matters more than it might seem. When AI agents work invisibly, two problems compound:

• Late detection: You only discover something went wrong after the work is done — wasting compute and time, with no way to intervene mid-course
• No improvement signal: Without seeing intermediate behavior, you can't tell why a result was good or bad — which makes it hard to improve your prompts, tasks, and agent design

cmux-team is an AI observatory, not another automation black box. The terminal panes aren't decoration — they're the product. A 10-second glance at a Conductor pane is often enough to catch a problem that would otherwise only surface at the end.

To peek into another project's runtime state without leaving your shell: cmux-team status --project-root /path/to/other (read-only by default; cross-project writes require --project-root-confirm or CMUX_TEAM_PROJECT_ROOT_CONFIRM=1).

The design principle: reduce cognitive load by making the process visible, not by hiding it.

What you do: Give Claude instructions in natural language. What Claude does: Splits panes via cmux, launches sub-agents, monitors them, and integrates results — all in plain sight.

Prerequisites

• Claude Code installed
• cmux installed
• bun installed (required for the Manager daemon)
• Running Claude Code inside a cmux session
• Nerd Font (recommended) — enhances TUI dashboard icons

  brew install --cask font-hack-nerd-font
  

  Works without Nerd Font (falls back to Unicode symbols). Set CMUX_NERD_FONT=0 to use fallback icons explicitly.

Installation

npm install -g @hummer98/cmux-team

About auto-update

The daemon detects new versions via update-notifier and surfaces them in the TUI banner. Install is always manual — run npm i -g @hummer98/cmux-team@<latest> yourself to avoid surprises across mixed Node environments (Volta / nvm / Homebrew).

Two modes (default: off):

mode	behavior
off	do nothing (no registry access)
notify	detect every 12h and show a TUI banner; no install

Configuration (precedence: env > config > default):

• CMUX_TEAM_AUTO_UPDATE=off|notify (also accepts 0|false as off)
• .team/config.json: { "autoUpdate": "off" | "notify" }

Related:

• NO_UPDATE_NOTIFIER=1 disables detection (standard update-notifier env var)
• Boot log: auto_update_config mode=<mode> source=<env|config|default>

Breaking change (v4.5.0, T294):

• The task mode (auto-creation of update tasks) is removed. CMUX_TEAM_AUTO_UPDATE=task|1|true and .team/config.json: autoUpdate: "task" | true | false now exit with status 1.
• The cmux-team self-update subcommand is removed.
• Migration: set autoUpdate to notify (or off), then run npm install -g @hummer98/cmux-team@latest when the banner appears.

Configuration (.team/config.json)

Created per-project by cmux-team start. All keys are optional — the file can be edited by hand and is re-read on next start. General precedence: CLI flag > env var > .team/config.json > built-in default.