Install and Setup

Install

Two supported paths, both macOS only.

brew tap manaflow-ai/cmux
brew install --cask cmux
brew upgrade --cask cmux

Or download cmux-macos.dmg from the latest release and drag the app to Applications. After the first install the app updates itself through Sparkle, so you do not need to download again. On first launch macOS may ask you to confirm opening an app from an identified developer, so click Open.

A separate nightly build ships from main with its own bundle ID and its own Sparkle feed, so it runs side by side with stable.

cmux version        # e.g. cmux 0.64.22 (102) [ddd4a01bc]

The CLI

The Homebrew cask puts cmux on your PATH (/opt/homebrew/bin/cmux). It is a thin client for a Unix socket, so most commands need the app running.

cmux ping           # socket reachable?
cmux capabilities   # server capabilities as JSON
cmux identify       # server identity plus caller context

The socket defaults to ~/.local/state/cmux/cmux.sock. Override it with CMUX_SOCKET_PATH or the global --socket <path> flag.

Socket control mode

Socket access is a setting, not open by default. automation.socketControlMode in cmux.json selects the policy, and the default is cmuxOnly, meaning only processes running inside cmux terminals can drive it.

With password, precedence is --password, then the CMUX_SOCKET_PASSWORD environment variable, then the password saved in Settings.

Environment variables inside cmux terminals

cmux injects these, and the CLI uses them as implicit defaults so most commands need no --workspace or --surface.

These are protected at spawn time, so a workspace environment cannot override them, and neither can TERM, COLORTERM, or TERM_PROGRAM.

Wiring up agents

Two setup steps make agents feel native. First install the agent CLI so its binary is on PATH, then install hooks.

cmux hooks setup                    # every supported agent it can find
cmux hooks setup codex
cmux hooks setup --agent opencode
cmux hooks <agent> uninstall

Hooks give you notifications on turn end and permission prompts, plus session resume after a relaunch. Resume integrations exist for Claude Code, Codex, Grok, OpenCode, Pi, Amp, Cursor CLI, Gemini, Rovo Dev, Copilot, CodeBuddy, Factory, and Qoder. Claude Code goes through the cmux Claude wrapper when Claude integration is enabled in Settings.

Multi-agent launchers, each one a thin wrapper that turns spawned agents into real panes:

cmux claude-teams        # Claude Code teammate mode as native splits
cmux codex-teams         # Codex subagents as panes
cmux omo                 # OpenCode via oh-my-openagent
cmux omx                 # Oh My Codex
cmux omc                 # Oh My Claude Code

Config files and reload

cmux settings path       # print cmux.json paths
cmux config doctor       # diagnose config problems
cmux config validate     # syntax check
cmux reload-config       # reload cmux.json AND Ghostty config, no restart

Back up an existing cmux.json to a timestamped .bak before editing it. Session snapshots live under ~/Library/Application Support/cmux/, and agent hook session mappings under ~/.cmuxterm/.