cmux: The Native macOS Terminal Built for Running AI Coding Agents in Parallel

If you have ever run three Claude Code sessions at the same time in a stock terminal, you know the pain. Notifications are generic ("Claude is waiting for your input" — every single time), tab titles blur together, and there is no good way to tell which agent needs you without clicking into each pane one by one. cmux was built to fix exactly this.

What Is cmux?

cmux is an open-source, native macOS terminal application built on top of Ghostty, the GPU-accelerated terminal emulator. It wraps Ghostty's rendering engine (libghostty) in a Swift/AppKit shell and layers on top the features that matter when you are managing multiple AI coding agents simultaneously:

• Vertical tab sidebar showing git branch, linked PR status, working directory, listening ports, and the latest notification text for each workspace
• Agent-aware notification rings — when an agent needs input, its pane gets a blue visual ring and the sidebar tab lights up
• Notification panel with a single keyboard shortcut to jump to the most recent unread agent
• In-app split browser with a scriptable API so agents can interact with your dev server directly
• Socket and CLI API to script workspace creation, pane splits, keystrokes, and browser control from anywhere

It reads your existing ~/.config/ghostty/config, so your fonts, themes, and colors carry over instantly.

Why Not Just Use tmux or iTerm2?

Fair question. Here is the honest comparison.

cmux vs tmux

tmux is a terminal multiplexer that runs inside any terminal. It is text-based, highly composable, and works over SSH. It has no native notification system for AI agents — you would need to wire up OSC sequences yourself and build your own status line logic. The tab sidebar in cmux gives you live git branch, PR number, CWD, and agent notification text with zero configuration. tmux also runs inside existing terminals, so you are still at the mercy of whatever notification plumbing that terminal has (or does not have).

cmux vs iTerm2

iTerm2 is the veteran macOS terminal. It has excellent shell integration, triggers, and a mature notification system. But it is not built with AI agent workflows in mind — notifications do not carry workspace-level context, there is no sidebar showing agent state, and it is not GPU-accelerated. If you live in Claude Code, Codex, or OpenCode all day, iTerm2 will give you a generic macOS notification with no way to quickly surface which of your eight agents actually needs attention.

cmux vs Warp

Warp is a modern Electron-based terminal with AI features built in. It has good UX but uses Electron/Tauri under the hood, which means higher memory usage and slower startup compared to a native Swift app. cmux is intentionally not an AI orchestrator — it is a primitive that gives you the tools to run any agent (Claude Code, Codex, OpenCode, Gemini CLI, Aider, Kiro) side by side without locking you into one workflow.

Installation

Option 1: DMG (Recommended for First Install)

Download the latest .dmg from the releases page:

https://github.com/manaflow-ai/cmux/releases/latest/download/cmux-macos.dmg

Open it, drag cmux to your Applications folder, and launch it. cmux auto-updates via Sparkle from that point — you only need to download once.

Option 2: Homebrew

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

To update later:

brew upgrade --cask cmux

System requirements: macOS 14.0 or later, Apple Silicon or Intel.

On first launch macOS will ask you to confirm opening an app from an identified developer. Click Open.

Setting Up the CLI

The CLI is what lets you script cmux from inside or outside the app. Inside cmux terminals it works automatically. To use it from an external script or CI hook, create a symlink:

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

Test it:

cmux list-workspaces
cmux notify --title "Hello" --body "cmux CLI is working"

The Notification System

This is the core reason to use cmux if you run agents in parallel. There are three ways to send a notification into cmux.

1. CLI (Easiest)

cmux notify --title "Build Complete" --body "webpack finished in 4.2s"
cmux notify --title "Claude Code" --subtitle "Waiting" --body "Agent needs input"

2. OSC 777 (Shell / Any Language)

This is the RXVT escape sequence protocol. Works from any shell script or language that can write to stdout:

printf '\e]777;notify;My Title;Message body\a'

Shell function you can drop in .zshrc or .bashrc:

cmux_notify() {
  printf '\e]777;notify;%s;%s\a' "$1" "$2"
}

cmux_notify "Tests passed" "All 142 tests green"

From Python:

import sys

def notify(title: str, body: str):
    sys.stdout.write(f'\x1b]777;notify;{title};{body}\x07')
    sys.stdout.flush()

notify("Script done", "Processed 5000 rows")

From Node.js:

function notify(title, body) {
  process.stdout.write(`\x1b]777;notify;${title};${body}\x07`);
}

notify('Build done', 'webpack finished');

3. OSC 99 (Kitty Protocol — Richer)

If you need subtitles or notification IDs:

printf '\e]99;i=1;e=1;d=0;p=title:Build Complete\e\\'
printf '\e]99;i=1;e=1;d=0;p=subtitle:Project X\e\\'
printf '\e]99;i=1;e=1;d=1;p=body:All tests passed\e\\'

Use OSC 777 for most cases. Use OSC 99 only when you need subtitle fields.

Wiring Up Claude Code Hooks

This is probably the most useful setup step. Claude Code supports lifecycle hooks, so you can fire a cmux notification the moment an agent stops or completes a sub-task.

Step 1 — Create the hook script:

# ~/.claude/hooks/cmux-notify.sh
#!/bin/bash

# Skip silently if we're not running inside cmux
[ -S /tmp/cmux.sock ] || exit 0

EVENT=$(cat)
EVENT_TYPE=$(echo "$EVENT" | jq -r '.hook_event_name // "unknown"')
TOOL=$(echo "$EVENT" | jq -r '.tool_name // ""')

case "$EVENT_TYPE" in
    "Stop")
        cmux notify --title "Claude Code" --body "Session complete"
        ;;
    "PostToolUse")
        [ "$TOOL" = "Task" ] && cmux notify --title "Claude Code" --body "Agent finished sub-task"
        ;;
esac

chmod +x ~/.claude/hooks/cmux-notify.sh

Step 2 — Register the hook in Claude Code:

// ~/.claude/settings.json
{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/cmux-notify.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Task",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/cmux-notify.sh"
          }
        ]
      }
    ]
  }
}

Restart Claude Code. Now every time a session completes or a sub-agent finishes, the cmux pane gets a blue notification ring and the sidebar tab lights up. Press Cmd+Shift+U to jump straight to the most recent unread.

Key Keyboard Shortcuts

You will use these constantly once you have a few agents running.

The In-App Browser

One underrated feature: cmux ships with a split browser pane with a scriptable API ported from Vercel Labs' agent-browser. Open it with Cmd+Shift+L.

Agents running Claude Code can snapshot the accessibility tree of the browser, get element references, click, fill forms, and evaluate JavaScript — all without leaving the terminal. This is useful when an agent is working against a local dev server and you want it to verify UI changes or run through a form flow directly.

Is It Worth Trying?

Yes, if you:

• Run multiple AI coding agents in parallel (Claude Code, Codex, OpenCode, Gemini CLI, Aider)
• Are on macOS and want native performance over an Electron-based terminal
• Already use Ghostty and want agent-aware notifications without switching apps
• Want to script your workspace layout through a CLI or socket API

Maybe not yet, if you:

• Are on Linux or Windows (cmux is macOS-only, macOS 14+)
• Need SSH session support (not available yet)
• Rely on live process restore after a restart (layout restores but running shells/agents do not resume yet)
• Are happy with a single agent workflow where notifications are not a problem

The project is young (v0.61 at the time of writing, 4.5k GitHub stars) but actively maintained with 24 releases already shipped. It is free, open source under AGPL-3.0, and auto-updates silently. The nightly build runs alongside the stable app with its own bundle ID if you want to live on the edge.

If you regularly find yourself clicking through terminal panes to figure out which Claude Code session is blocked, cmux solves that problem specifically and solves it well.

Quick Links

• GitHub: https://github.com/manaflow-ai/cmux