Getting Started

cmux is a lightweight, native macOS terminal built on Ghostty for managing multiple AI coding agents. It features vertical tabs, a notification panel, and a socket-based control API.

Install

DMG (recommended)

Open the .dmg and drag cmux to your Applications folder. cmux auto-updates via Sparkle, so you only need to download once.

Homebrew

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

To update later:

brew upgrade --cask cmux

Verify installation

Open cmux and you should see:

• A terminal window with a vertical tab sidebar on the left
• One initial workspace already open
• The Ghostty-powered terminal ready for input

CLI setup

cmux includes a command-line tool for automation. Inside cmux terminals it works automatically. To use it from other terminals, open the command palette (⌘⇧P) and run Shell Command: Install 'cmux' in PATH. It links the bundled CLI into /usr/local/bin and asks for an administrator password if that folder needs one.

Or create the symlink yourself:

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

Then you can run commands like:

cmux list-workspaces
cmux notify --title "Build Complete" --body "Your build finished"

Make cmux your default terminal

To open ssh:// links and shell scripts from Finder in cmux instead of Terminal, choose cmux > Make cmux the Default Terminal in the menu bar, or run Make cmux the Default Terminal from the command palette.

Auto-updates

cmux checks for updates automatically via Sparkle. When an update is available you'll see an update pill in the titlebar. You can also check manually via cmux > Check for Updates in the menu bar.

Session restore (current behavior)

cmux restores layout and metadata after relaunch. Supported agent sessions can also resume when hooks have captured a native resume token.

See the session restore guide for agent hook setup and the supported resume matrix.

Requirements

• macOS 14.0 or later
• Apple Silicon or Intel Mac