Installation#

micromux ships a single binary, micromux. It is developed and fully supported on Linux and macOS; on Windows the TUI runs but the control plane does not (see platform support).

Homebrew#

The quickest way on macOS or Linux:

brew install --cask romnn/tap/micromux

From source#

With a Rust toolchain installed:

cargo install --locked micromux-cli

This builds the full binary, including the MCP server. For a lean, TUI-only build with the MCP server compiled out:

cargo install --locked --no-default-features micromux-cli

Verify#

micromux --version
micromux --help

micromux --version prints the release followed by the control protocol version, such as 0.2.0 (protocol 3.10). Clients and sessions built from different releases work together as long as their protocol major matches.

micromux --help lists the subcommands:

$ micromux --help
 
A micromux subcommand. With no subcommand, micromux runs the TUI for the current project
 
Usage: micromux [OPTIONS] [COMMAND]
 
Commands:
  attach  Attach the TUI to an already-running micromux session
  ctl     Control a running micromux session over its local endpoint (dogfoods the control protocol)
  mcp     Run the MCP server over stdio (configure once in Claude Code / Codex like playwright-mcp)
  serve   Run the supervisor headless (no TUI), serving the control plane until stopped. Intended for agent-managed sessions — see the MCP `start_session`/`stop_session` tools
  help    Print this message or the help of the given subcommand(s)
 
Options:
  -c, --config <CONFIG_PATH>  path to config file
      --strict <STRICT>       enable strict mode [env: MICROMUX_STRICT=] [possible values: true, false]
      --color <COLOR_CHOICE>  enable or disable color [env: MICROMUX_COLOR=]
  -v, --verbose...            Increase logging verbosity
  -q, --quiet...              Decrease logging verbosity
      --log <LOG_LEVEL>       Log level. When using a more sophisticated logging setup using RUST_LOG environment variable, this option is overwritten. [env: MICROMUX_LOG_LEVEL=]
      --log-file <LOG_FILE>   Log file [env: MICROMUX_LOG_FILE=]
      --no-pretty-json-logs   show structured JSON logs as raw JSON in the TUI (also configurable via `ui: { pretty_json_logs: false }`) [env: MICROMUX_NO_PRETTY_JSON_LOGS=]
      --no-control            disable the agent control plane (also configurable via `control: { enabled: false }`) [env: MICROMUX_NO_CONTROL=]
  -h, --help                  Print help
  -V, --version               Print version

With no subcommand, micromux runs the TUI for the current project. The others — attach, ctl, serve, and mcp — are covered under the relevant sections.

Platform support#

Platform	TUI	Control plane (`attach` / `ctl` / `mcp` / `serve`)
Linux	✅	✅
macOS	✅	✅
Windows	✅	❌ not yet

On Windows the TUI runs, but the control plane is not yet available, and stopping a service kills it immediately without a graceful-termination phase. Windows named-pipe support is planned.

Next: the Quick start.