cmux: The Terminal Emulator Built for Managing Multiple AI Coding Agents

Hook

When you're running three AI coding agents in parallel—one debugging your API, another writing tests, and a third refactoring components—how do you know which terminal just asked for your approval? cmux solves this with a notification system that other terminal emulators simply don't have.

Context

The explosion of AI coding assistants like Claude Code, GitHub Copilot, and OpenAI Codex has created a workflow problem that traditional terminal emulators weren't designed to handle. Developers now routinely run multiple autonomous agents simultaneously: one agent might be iterating on frontend components while another debugs backend services and a third writes documentation. Each agent operates in its own terminal session, spawning processes, running tests, and occasionally pausing to request human input.

The problem isn't running multiple sessions—tmux and iTerm2 have handled that for decades. The problem is attention management. When Agent B in tab 7 hits an error and needs your decision, how do you notice? Developers were hacking together solutions: terminal bell notifications that spam your notification center, custom shell prompts with OSC sequences, elaborate tmux status bars. Meanwhile, agents that could interact with browsers were limited to clunky Selenium setups or required separate browser automation tools. cmux emerged from this specific pain point: a macOS developer at manaflow-ai needed a terminal that understood AI agent workflows natively, with visual notifications, workspace isolation, and browser control as first-class features rather than bolted-on scripts.

Technical Insight

cmux's architecture is a masterclass in leveraging existing infrastructure while adding targeted features. Rather than reimplementing terminal rendering—a monumental task involving font rendering, GPU acceleration, and escape sequence parsing—it wraps libghostty, the C library that powers Ghostty. This gives cmux immediate access to Ghostty's performance characteristics (GPU-accelerated rendering, <100ms startup) while letting the team focus on workspace orchestration in Swift/AppKit.

The notification system works through OSC (Operating System Command) escape sequences, specifically OSC 9, OSC 99, and OSC 777. When an AI agent needs attention, it emits these sequences that cmux intercepts and translates into visual indicators. A blue ring appears around the terminal pane, the tab name highlights in the vertical sidebar, and optionally a macOS notification fires. Here's how an agent would trigger this:

# Agent sends notification when pausing for input
echo -e "\033]99;Awaiting approval for DB migration\007"

# Or using OSC 777 for notification with identifier
echo -e "\033]777;notify;agent-backend;Build failed - review logs\007"

cmux parses these sequences before they reach libghostty, maintaining a notification state map per pane. When you click a highlighted tab, cmux marks that notification as read and removes the visual indicator. This is conceptually simple but operationally critical—it transforms parallel agent sessions from "impossible to track" to "obvious at a glance."

The workspace system extends beyond basic tmux-style panes. Each workspace is a first-class object in cmux's data model, storing not just terminal sessions but git repository metadata, active branch, PR status, and remote SSH connection state. When you split a pane in an SSH workspace, the new pane inherits the SSH connection automatically. More importantly, if you launch the integrated browser in that workspace, cmux routes browser traffic through the SSH tunnel. This means localhost:3000 in the browser actually hits localhost:3000 on the remote machine, not your Mac. For AI agents testing code on remote dev boxes, this eliminates an entire category of manual port forwarding.

The browser integration is where cmux gets genuinely innovative. It ports agent-browser's accessibility tree API into the native macOS app using WebKit and Swift's Accessibility framework. An agent can control the browser programmatically:

# Python agent using cmux socket API
import socket
import json

def browser_click(selector):
    sock = socket.socket(socket.AF_UNIX)
    sock.connect("/tmp/cmux.sock")
    
    command = {
        "action": "browser.interact",
        "workspace": "frontend-dev",
        "selector": selector,
        "operation": "click"
    }
    
    sock.send(json.dumps(command).encode())
    response = json.loads(sock.recv(4096))
    sock.close()
    return response

# Agent testing a signup flow
browser_click("#email-input")
browser_type("test@example.com")
browser_click("button[type=submit]")
snapshot = browser_snapshot()  # Returns accessibility tree

The accessibility tree snapshot gives agents a semantic representation of the page—not just pixels, but actual button labels, form field names, and heading hierarchy. This is far more reliable than vision-based browser agents that struggle with dynamic UIs. Under the hood, cmux uses AXUIElement APIs to walk the WebKit rendering tree, serializing it to JSON that agents can parse.

One subtle architectural decision: cmux reads your existing Ghostty configuration files (~/.config/ghostty/config) rather than implementing its own config system. This means your terminal behavior—font, colors, key bindings—comes from Ghostty's config, while cmux-specific features (workspace layouts, notification preferences, browser settings) live in ~/.config/cmux/config.toml. This separation prevents the project from becoming a config management nightmare and lets users leverage the Ghostty ecosystem's existing themes and tools.

Gotcha

The macOS-only limitation is non-negotiable. cmux uses AppKit, Swift, and macOS-specific APIs like AXUIElement throughout its codebase. There's no "port to Linux" on the roadmap because that would mean rewriting the entire UI layer. If your team runs mixed operating systems, you'll create workflow fragmentation—some developers get the notification system and vertical tabs, others don't.

The libghostty dependency creates version coupling risk. cmux doesn't vendor libghostty; it dynamically links against whatever Ghostty version you have installed. When Ghostty introduces breaking changes to its config format or internal APIs, cmux can break until it catches up. During Ghostty's rapid development phase (it's still pre-1.0), this has caused issues. For example, Ghostty changed how it handles font fallback in version 0.8, which temporarily broke cmux's font rendering until a patch release. For production-critical workflows, this coupling is concerning. Additionally, the browser integration only works with local dev servers or SSH-forwarded ports—it can't authenticate to external services that require OAuth flows, since there's no cookie/session persistence across cmux restarts. The browser is a testing tool, not a replacement for Chrome DevTools.

Verdict

Use cmux if you're a macOS developer running multiple AI coding agents simultaneously and constantly losing track of which agent needs attention. The notification system with visual indicators, combined with vertical tabs showing git context, directly solves the multi-agent orchestration problem. The integrated scriptable browser is invaluable if your agents need to test UIs on localhost or remote dev servers without Selenium overhead. It's also compelling if you're already invested in Ghostty and want workspace management without Electron bloat. Skip cmux if you're on Linux/Windows, need cross-platform tooling consistency in your team, or don't work extensively with AI agents where the notification features provide clear ROI. Also skip if you need a mature, battle-tested terminal with a decade of community plugins and Stack Overflow answers—cmux is powerful but young, and you'll occasionally hit undocumented edge cases. Traditional iTerm2 + tmux remains the safer choice for teams that need stability over cutting-edge AI workflow features.