cmux: A Ghostty-Based macOS Terminal for Parallel Agents

Introduction

Running several terminal-based coding agents—or many long-lived shells across worktrees—compresses two pain points into the same UX: finding the right surface among a pile of windows, and telling which session genuinely needs attention instead of burying signals in duplicates of every other tab bar. cmux is a native macOS host for that pattern: workspaces with vertical sidebar tabs, split panes, a pane-level notification system hooked to OSC sequences as well as a CLI hook, GPU-backed terminal rendering via Ghostty’s libghostty, and optionally an embedded browser pane with programmatic control comparable to tooling like agent-browser.

The project pitches itself explicitly as primitives—terminal, browser, notifications, workspaces—not a turnkey “agent orchestrator” UI. Practically that means cmux complements whatever CLIs or agents you already run; whether that tradeoff nets out for you hinges on caring about macOS-native integration versus cross-platform multiplexing conventions you already rebuilt in tmux.

Cover: upstream documentation screenshot for vertical tabs/splits (docs/assets/vertical-horizontal-tabs-and-splits.png in the GPLv3-licensed repo on GitHub).

Ghostty renders; cmux composes

cmux is not a fork of the Ghostty app. Ghostty exposes libghostty; cmux embeds it the way browsers embed engines—different product boundaries, shared rendering chops. Upshot for users who already standardized on Ghostty: themes, fonts, and colors carry over from ~/.config/ghostty/config, while window chrome, workspaces, splits, browser, and notification wiring belong to cmux. If someone wanted “Ghostty minus nothing,” they stick with Ghostty; cmux is for people who prioritize labeled workspaces over the stock tab strip.

Sidebar, splits, notifications: judgment call

Sidebar tabs deliberately carry repo-shaped context—things like Git branch, working directory, listening ports, and linked PR cues—plus the tail of pending notification copy. Split panes nest per workspace instead of spawning another OS window whenever you fork an agent pane.

Notifications are cmux’s most opinionated wedge. Standard-terminal OSC sequences (9, 99, 777) bubble into visible rings across the relevant pane alongside sidebar emphasis; cmux notify exists where hooks need to augment or replace OSC. The motivating story from the makers is pragmatic: aggregate macOS notifications from agents routinely collapse into the same nondescript “waiting” copy, stripping which pane stalled you. Routing attention through pane chrome targets that ambiguity directly—provided your stack actually emits OSC or integrates hooks. If neither is true yet, adoption is upfront wiring work rather than flipping a checkbox.

Embedding a browser is the other heavyweight feature: split beside the shell, scripted driving of page structure and interaction without standing up disposable browser automation for every tweak, plus optional cookie/session import from installed browsers—useful mainly when SSO-heavy dev servers make “fresh ephemeral profile” unbearable each run.

Automation and SSH-shaped workspaces

A CLI and socket API underpin layout and input (workspaces, splits, keystrokes, browser control)—the natural place for “focus this workspace after CI fails” orchestration layered on Claude Code hooks or bespoke scripts rather than rewriting macOS bridging per tool.

cmux ssh user@remote warrants a sharper mental model: it creates a workspace whose network shape matches remote reality (including browser panes seeing remote localhost, per upstream docs—local-only mental models break here), plus conveniences such as SCP-backed drag upload of imagery into sessions. Compare that to multiplexing shells you already multiplexed purely on localhost: different scope, overlapping surface area.

How this differs from tmux (and restore caveats)

tmux lives inside a terminal emulator; survives SSH drops; restores layout purely on the POSIX side independent of Cocoa. cmux trades that universality for a hosted macOS experience—GUI affordances around attention, sidebar metadata, baked-in browser—not a substitution for unattended server sessions detached from graphical life.

Upstream is explicit where session restore stops: quitting persistently reloads layouts, cwd, browser URLs/history where applicable, terminal scrollback (best effort), and explicitly integrated resume paths for agents when tokens exist—not a snapshot of arbitrary in-process Vim or raw shell transcripts. Evaluate against what you genuinely need resurrected versus what stays cheap to re-drive from shell history.

Install, licensing, platform

Availability is macOS-only today via DMG (Sparkle-backed updates per upstream) or brew tap manaflow-ai/cmux / brew install --cask cmux.

Code ships GPL-3.0-or-later publicly; README advertises parallel commercial relicensing inquiries for incompatible orgs—that matters wherever GPL copyleft obligations on distribution or coupling do not fit your compliance story.

Canonical detail for versions, deltas, shortcuts, nightly builds: the same cmux repo—this article is explanatory, not a substitute for changelog-level truth.

Conclusion

cmux is worth evaluating when pane-level urgency and repo-scoped tab chrome outweigh staying inside a multiplexed terminal you already scripted to death—or when Electron-forward “agent workspaces” grated on responsiveness but you still want browser-in-the-shell without separate automation plumbing. Fail the filter early if Linux is mandatory, OSC/hook instrumentation is undesirable, tmux-tier SSH persistence is sacred, or GPL friction blocks adoption. Prefer the changelog and bundled docs on GitHub whenever behavior drifts faster than outsider summaries.