cmux: A Ghostty-Based macOS Terminal Built for AI Agent Workflows

The Problem: Agent Notifications Without Context

The README's author describes a concrete pain: running many Claude Code and Codex sessions in Ghostty splits, relying on macOS notifications that only say 'Claude is waiting for your input' with no detail. With enough tabs, titles become unreadable. cmux solves this by adding a sidebar with vertical tabs that show git branch, linked PR status, working directory, listening ports, and the latest notification text per workspace. It also draws a blue ring around a pane and lights up the tab when an agent needs attention. This is for developers who live in the terminal and want to know which of several agents is blocked without hunting through every split.

How It Works: libghostty, Sidebar, and Notification Sequences

cmux is a native macOS app written in Swift and AppKit. It uses libghostty for terminal rendering and reads your existing ~/.config/ghostty/config for themes, fonts, and colors. The notification system listens for terminal escape sequences, specifically OSC 9, OSC 99, and OSC 777. It also provides a CLI command, cmux notify, that you can wire into agent hooks for tools like Claude Code and OpenCode. When an agent emits one of those sequences, the pane gets a blue ring and the tab lights up. Cmd+Shift+U jumps to the most recent unread notification. The sidebar is not static: it updates with git branch, PR status, working directory, listening ports, and the latest notification text for each workspace.

Getting Started: DMG, Homebrew, and First Launch

The recommended install is a DMG download from the releases page. Open the .dmg and drag cmux to your Applications folder. The app auto-updates via Sparkle, so you only download once. Alternatively, use Homebrew: brew tap manaflow-ai/cmux then brew install --cask cmux. To update later, run brew upgrade --cask cmux. On first launch, macOS may ask you to confirm opening an app from an identified developer. The README shows a button labeled Open. After install, cmux reads your existing Ghostty config, so themes and fonts carry over without extra setup. For SSH, you run cmux ssh user@remote to create a workspace for a remote machine, with an optional --command flag to run an initial command in the first remote terminal.

The Scriptable Browser and CLI/Socket API

cmux includes an in-app browser that can be split alongside the terminal. The browser has a scriptable API ported from agent-browser, originally from Vercel Labs. Agents can snapshot the accessibility tree, get element refs, click, fill forms, and evaluate JavaScript. The README gives an example: split a browser pane next to your terminal and have Claude Code interact with your dev server directly. Everything is scriptable through the CLI and a socket API. You can create workspaces and tabs, split panes, send keystrokes, and open URLs in the browser. This is a different approach from GUI orchestrators that lock you into a workflow; cmux provides primitives and leaves the workflow to you.

Limitations and Wrong Use Cases

cmux is macOS-only. The README describes it as a native macOS app built with Swift and AppKit. If you need a cross-platform terminal, this is not it. The project is also in active nightly development; the release list shows a Nightly (cmux-next) build from 2026-10-04 and cmux-app-ffi builds tagged 2026-11-03. The nightly cadence suggests frequent changes, which could mean instability or breaking changes. Another limitation: the notification system depends on agents emitting OSC 9/99/777 sequences. If your agent does not emit those, you must wire cmux notify into hooks manually.

Alternative: Stock Ghostty or tmux-Based Setups

The README's author came from Ghostty with split panes and native macOS notifications. That is the direct alternative: use Ghostty as-is and rely on its native split support and macOS notifications. The difference is that Ghostty does not have the sidebar, notification rings, or the in-app browser. Another alternative is tmux, which the README mentions in the context of Claude Code Teams: cmux claude-teams runs Claude Code's teammate mode without tmux required. If you already use tmux for session management, you can get similar multitasking, but you lose the native macOS integration and the scriptable browser. The trade-off is between a purpose-built tool with agent-specific features and a general-purpose terminal multiplexer that you configure yourself.

Maintenance, License, and Upgrade Costs

The README states the project is GPL-licensed, and package.json declares GPL-3.0-or-later. That has implications if you plan to redistribute or embed code, though this is not legal advice. The project has a nightly release channel (Nightly (cmux-next)) alongside the DMG download. Auto-updates via Sparkle mean you get updates without manual intervention, but that also means you may receive changes without review. The Homebrew cask path requires tapping manaflow-ai/cmux, so you depend on that tap staying maintained.

Editorial conclusion

Adopt cmux if you are a macOS developer running multiple AI coding agents in parallel and you want a native terminal that reads your existing Ghostty config, adds visual notification cues, and exposes a CLI/socket API for automation. Skip it if you need Linux or Windows support, or if you prefer a terminal that stays close to stock Ghostty without extra layers. Before adopting, verify the GPL license fits your distribution plans, check the nightly release cadence for stability, and confirm that the OSC 9/99/777 notification sequences work with your specific agent hooks.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes