# 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)

[Download for Mac](https://cmux.com/download/confirmation?dl=1)

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
```

On first launch, macOS may ask you to confirm opening an app from an identified developer. Click **Open** to proceed.

## 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.

cmux does not checkpoint arbitrary live process state. Unsupported terminal apps such as tmux, vim, and ordinary shells reopen as normal terminals.

See the [session restore guide](https://cmux.com/docs/session-restore) for agent hook setup and the supported resume matrix.

## Requirements

-   macOS 14.0 or later
-   Apple Silicon or Intel Mac

Canonical: https://cmux.com/docs/getting-started

Documentation index: https://cmux.com/llms.txt