Installation itself isn't difficult, but there are a few details that, if missed, will cause problems when you try to use the CLI later. This article walks through the complete process from installation to verification, and explains why the CLI setup matters and when you'll need it.

Two Installation Methods

Option 1: DMG (Recommended)

Download the .dmg from the official website, open it, and drag CMUX to the Applications folder — that's it. Updates are handled automatically by CMUX's built-in Sparkle framework; no manual management needed.

The first time you open it, macOS may show a confirmation dialog asking if you want to open an application from an identified developer. Just click Open.

Why this method: Simple, auto-updating, download once and you're done.

Option 2: Homebrew

If you prefer managing tools through a package manager:

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

To update later:

brew upgrade --cask cmux

Both methods install the same application — use whichever you're comfortable with.

Verify the Installation

Open CMUX. You should see:

A vertical tab sidebar on the left (this is CMUX's signature feature, not tmux-style horizontal tabs)
An initial workspace already created
A terminal ready to accept input

If you see all three, installation was successful.

CLI Setup: Why Bother

CMUX includes a cmux CLI tool that lets you control CMUX directly from the terminal — listing workspaces, sending notifications, running automation scripts all rely on it.

Inside a CMUX terminal, the CLI is automatically available — no additional setup needed.

The issue: if you run it from another terminal (iTerm2, the system Terminal), the cmux command won't be found. To fix this, create a symlink:

sudo ln -sf "/Applications/cmux.app/Contents/Resources/bin/cmux" /usr/local/bin/cmux

Once done, cmux is callable from any terminal:

# List all workspaces
cmux list-workspaces
 
# Send a notification
cmux notify --title "Build Complete" --body "Your build finished"

This setup becomes valuable later when you're working with custom commands, CI integrations, and automation scripts — do it during your initial install and you won't have to think about it again.

Auto-Update Mechanism

DMG users don't need to worry about manual updates. CMUX checks for updates automatically via Sparkle, and you'll see an update prompt in the title bar when a new version is available. You can also trigger it manually: menu bar → cmux > Check for Updates.

Homebrew users update with brew upgrade --cask cmux.

Quick System Requirements Check

macOS 14.0 (Sonoma) or later
Both Apple Silicon and Intel Macs are supported

Once you're installed and running, the next step is understanding CMUX's three-layer structure — this is what takes you from "kind of using it" to actually knowing how it works: Workspaces, Panes, and Surfaces: CMUX's Three-Layer Structure Explained.