cmux: A Ghostty-Based macOS Terminal for Running AI Coding Agents in Parallel

The problem cmux targets: too many agent tabs, no signal about which one is stuck

The README opens with a concrete complaint from the author. Running many Claude Code and Codex sessions in parallel inside Ghostty split panes meant relying on native macOS notifications, and the notification body was always the same string: "Claude is waiting for your input". With enough tabs open, the titles stop being readable either. So the failure mode is not that the terminal is slow. It is that the terminal gives you no way to tell which of eight panes is blocked on you.

cmux is for that specific situation. It is a macOS-only terminal built in Swift and AppKit on top of libghostty, with a sidebar of vertical tabs that carries per-workspace context: git branch, linked PR status and number, working directory, listening ports, and the latest notification text. The audience is narrow by design. If you run one agent at a time in one window, the sidebar is overhead. If you run a fleet, it is the whole point.

The README also states what cmux is not: it is not an orchestrator that imposes a workflow. The "Zen of cmux" section calls it "a primitive, not a solution", and says the author avoided Electron and Tauri orchestrators partly for performance and partly because GUI orchestrators lock you into their model.

How cmux is put together: libghostty rendering, OSC sequences, and a socket API

Three mechanisms are visible in the repository and README.

First, rendering. cmux uses libghostty for the terminal surface, and the README states it reads your existing ~/.config/ghostty/config for themes, fonts and colors. That means your Ghostty setup carries over rather than being re-entered in a cmux-specific format. It also means cmux inherits Ghostty's configuration surface, including the parts cmux does not document.

Second, notifications. The README says the notification system picks up terminal sequences OSC 9, OSC 99 and OSC 777, and that there is a CLI command, cmux notify, intended to be wired into agent hooks for Claude Code and OpenCode. When a notification arrives, the pane gets a blue ring and the tab lights up in the sidebar. Cmd+Shift+U jumps to the most recent unread. This is the mechanism that replaces the useless "waiting for input" body: the signal moves from a macOS notification banner into the terminal chrome itself.

Third, programmability. The README describes a CLI and a socket API for creating workspaces, splitting panes, sending keystrokes, and driving the browser. The in-app browser exposes a scriptable API ported from vercel-labs/agent-browser, so an agent can snapshot the accessibility tree, get element refs, click, fill forms and evaluate JS. The repository layout matches this: there are CLI/, Sources/, Packages/, Native/, cmux-browser/ and TunnelExtension/ directories at the top level, plus a package.json that pulls in ProseMirror, React and SolidJS for webview work and Biome for linting. The mixed Swift and TypeScript surface is real, not incidental.

Installing cmux on macOS and running a first remote workspace

The README gives two install paths. The recommended one is the DMG from the latest GitHub release: open the .dmg and drag cmux to Applications. The README states cmux auto-updates via Sparkle, so the download happens once. On first launch macOS may ask you to confirm opening an app from an identified developer; the README says to click Open.

The second path is Homebrew, which is the one worth putting in a script because it also gives you an upgrade command. The README gives these two commands verbatim:

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

Running them installs the cask from the manaflow-ai tap. To update later, the README gives this command:

brew upgrade --cask cmux

After the install completes, cmux appears in your Applications folder and launches like any other macOS app.

A first real use: SSH workspaces and Claude Code Teams

The README's SSH example is the clearest demonstration of what a workspace means in cmux. Running the command below creates a workspace for a remote machine rather than a plain SSH session in a tab:

cmux ssh user@remote

Two details in the README are worth noting because they change how the remote session behaves. You can pass an initial command that runs once in the first remote terminal, using the --command flag with a quoted argument, and browser panes in that workspace route through the remote network so localhost resolves on the remote side. Dragging an image into a remote session uploads it over scp.

The second entry point is Claude Code's teammate mode, which the README says runs with one command and spawns teammates as native splits with sidebar metadata and notifications, without tmux:

cmux claude-teams

Both commands assume cmux is already installed and on your PATH, which the Homebrew cask handles.

What cmux does not do, and where it is the wrong tool

The most obvious boundary is the platform. The README describes a native macOS app built with Swift and AppKit, and the install section offers a DMG and a Homebrew cask. There is no Linux or Windows path documented. People searching for a Linux alternative to cmux are looking for something the README does not provide.

A second limitation is that the notification system depends on agents emitting the right sequences or on you wiring cmux notify into hooks. If your agent does not emit OSC 9, OSC 99 or OSC 777, and you do not add a hook, the blue ring and the sidebar highlight never fire. The README names Claude Code and OpenCode as the hook targets; it does not claim universal agent support.

A third point is the licensing situation as it appears in the repository. The README says cmux is "Free and GPL-licensed". The package.json declares "GPL-3.0-or-later", and the top-level entries include LICENSE, CLA.md and THIRD_PARTY_LICENSES.md. The repository metadata supplied alongside the project lists the licence as unknown, which is a discrepancy worth resolving by reading LICENSE directly rather than trusting either summary. If you plan to bundle cmux or link against its code, that difference matters.

Finally, the README does not document rollback or downgrade behaviour. It says Sparkle handles auto-updates, and it offers brew upgrade --cask cmux, but nothing about pinning a version or reverting a bad nightly. The releases list includes a nightly channel dated 2026-02-15 alongside stable tags, so if you install from the stable cask you are on a different track than nightly users, and the README is silent on how to move between them.

How cmux differs from Ghostty and from Electron orchestrators

The natural comparison is Ghostty itself, since cmux embeds libghostty and reads the same config file. The difference is not rendering. It is the sidebar and the notification layer. Ghostty gives you a terminal surface and split panes; deciding which pane needs attention is left to you and to macOS notifications, which is exactly the problem the README describes. If you like Ghostty's rendering but want per-workspace metadata (branch, PR, ports, last notification) visible at a glance, cmux is the same engine with that layer added. If you do not want that layer, staying on Ghostty costs you nothing and removes a dependency on a project whose last push to main was on 2026-02-15.

The other comparison is against GUI orchestrators. The README explicitly says most orchestrators the author tried were Electron or Tauri apps, that the performance bothered him, and that GUI orchestrators lock you into their workflow. cmux's counter-position is that it ships primitives (workspaces, splits, tabs, a browser, a CLI) and leaves the workflow to you. That is a real architectural difference: an orchestrator decides how agents are spawned and supervised, while cmux gives you cmux claude-teams and cmux ssh and lets you compose the rest. The trade-off is that you have to do the composing. There is no opinionated dashboard, and the README's own framing ("What you build with the primitives is yours") is a description of work you will have to do.

Maintenance, upgrade cost, and licence implications

The release history shows a stable line at v0.64.22 and v0.64.21, both dated 2026-08-03, and a nightly build dated 2026-02-15. The last push to the default branch was on 2026-02-15, which is more than six months before today. On that evidence, cmux should not be described as actively developed. The stable tags are older than the nightly entry, and the repository has not received a push since February. Anyone evaluating cmux for a team should treat that as the primary maintenance signal and check the CHANGELOG.md and releases page directly rather than relying on this article's reading of two dates.

The upgrade path is low friction if you installed via Homebrew, because brew upgrade --cask cmux is a single command, and the DMG path auto-updates through Sparkle. The cost is not in upgrading; it is in the absence of a documented downgrade route if an update breaks a workflow you depend on.

On licensing, the README says GPL-licensed and package.json says GPL-3.0-or-later, with a CLA.md present. GPL-3.0-or-later is a copyleft licence, which has implications for redistribution and for combining cmux code with your own. This article is not legal advice; if you intend to ship something derived from cmux, read LICENSE and THIRD_PARTY_LICENSES.md and get your own review.

Editorial conclusion

Adopt cmux if you run several Claude Code or Codex sessions at once on a Mac and already keep a Ghostty config you want to reuse; the vertical sidebar and the OSC 9/99/777 notification path are the parts that solve a real problem. Skip it if you work on Linux, or if you want a GUI orchestrator that decides your agent workflow for you, since the README describes cmux as a primitive rather than a solution. Before committing, verify three things: that the CLI subcommands you plan to script (cmux ssh, cmux claude-teams, cmux notify) exist in the build you install, that cmux.json custom commands load from your project root, and that the GPL-3.0-or-later terms in package.json match how you intend to redistribute anything you build on top of it.

Frequently asked questions

Official sources

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