cmux: Building a Terminal for the Age of AI Coding Agents
Hook
When you’re running three AI coding agents simultaneously—Claude on the API refactor, Codex on test coverage, Gemini debugging production—how do you know which one just finished and needs your attention? Generic terminal notifications don’t cut it anymore.
Context
AI coding agents have fundamentally changed how we write software. Tools like Claude Code, GitHub Codex, and OpenCode can refactor entire codebases, write comprehensive test suites, and debug complex issues autonomously. But they’ve created a new problem: context-switching hell.
A typical AI-assisted workflow involves spinning up multiple agents in parallel, each working on different features or bugs. You might have Claude refactoring authentication logic in one terminal, Codex adding API endpoints in another, and a third agent running integration tests. They all produce the same generic macOS notification: “Terminal - activity in session.” Your dock bounces. Which agent finished? Which one hit an error? You’re stuck clicking through tabs, checking each terminal, losing your flow state. Traditional terminal multiplexers like tmux were built for managing YOUR sessions, not for managing multiple autonomous agents competing for your attention. cmux was built to solve exactly this problem—a terminal designed from the ground up for the multi-agent development workflow.
Technical Insight
cmux takes an architectural approach that’s both pragmatic and ambitious: wrap libghostty for terminal rendering performance, then layer on native macOS UI chrome specifically designed for agent workflows. The core insight is treating Ghostty as a rendering primitive while building workspace and notification abstractions on top.
The application is structured around three key components. First, there’s the Ghostty integration layer—cmux links against libghostty.dylib and uses Swift/AppKit to wrap the GPU-accelerated terminal renderer. This means you get Ghostty’s exceptional performance (sub-10ms input latency, hardware acceleration) while maintaining full compatibility with existing Ghostty configuration files. Your themes, keybindings, and font settings just work.
Second, the workspace/surface abstraction provides the organizational model. A “workspace” in cmux is analogous to a tmux session—a collection of terminal panes with associated metadata like git branch, working directory, and PR status. Each pane (or “surface” in cmux terminology) can have a custom label, notification state, and visual indicator. The sidebar renders these as vertical tabs with rich context:
// Example of workspace metadata structure
struct WorkspaceMetadata {
let id: UUID
let label: String
let gitBranch: String?
let workingDirectory: URL
let prStatus: PRStatus?
var notificationText: String?
var hasUnreadActivity: Bool
var surfaces: [Surface]
}
struct Surface {
let id: UUID
let label: String
let notificationRing: RingColor?
let processInfo: ProcessInfo
}The third component is the scriptability layer, which is where cmux truly shines for AI agent workflows. The application exposes both a CLI tool and a Unix socket API for programmatic control. This means your AI agents—or the orchestration scripts managing them—can create workspaces, split panes, set notification states, and update metadata without any manual intervention.
Here’s a practical example of how you’d script an AI agent workflow:
#!/bin/bash
# Launch three AI coding agents with proper workspace isolation
# Create workspace for API refactor agent
cmux workspace create \
--label "Claude: API Refactor" \
--dir ~/project \
--branch feature/api-v2
# Split and configure the pane
cmux surface split --vertical
cmux surface set-label "API Agent Output"
cmux surface set-notification "Waiting for Claude..."
# Start the agent with notification hooks
claude-code refactor api/ \
--on-start "cmux surface set-notification 'Refactoring in progress'" \
--on-complete "cmux surface set-ring blue" \
--on-error "cmux surface set-ring red"
# Create separate workspace for test coverage agent
cmux workspace create \
--label "Codex: Test Coverage" \
--dir ~/project \
--branch feature/test-improvements
codex generate-tests \
--coverage-target 80 \
--on-complete "cmux surface set-notification 'Added 47 tests'"When agents complete or encounter errors, the sidebar lights up with specific visual indicators. Blue rings mean successful completion, red means errors, and the notification text shows agent-specific status. You can glance at the sidebar and instantly know: “Claude finished the refactor, Codex is still running tests, and Gemini hit a type error on line 342.”
The integrated browser component adds another dimension. cmux embeds a WebKit view with a scriptable API based on agent-browser, exposing accessibility tree snapshots, element interaction, and JavaScript evaluation. This is crucial for agents working on frontend code:
# Agent can interact with dev server directly
cmux browser navigate http://localhost:3000
cmux browser snapshot --accessibility > dom_tree.json
cmux browser click "#submit-button"
cmux browser eval "document.querySelector('.error').textContent"An agent debugging a React component can spawn a dev server, navigate to the problematic page, interact with elements, and capture error states—all from the same terminal environment where it’s editing code. The browser pane sits alongside terminal panes in the workspace, maintaining context.
The socket API uses a simple JSON protocol for more complex integrations. You can build orchestration tools that monitor all workspaces, aggregate agent status, and implement custom routing logic for when multiple agents finish simultaneously. The architecture is deliberately unopinionated about workflow—cmux provides primitives (workspaces, surfaces, notifications, browser control) and lets you compose them into whatever multi-agent pipeline makes sense for your team.
Gotcha
The most obvious limitation is the macOS-only constraint. cmux is built on AppKit and uses macOS-specific frameworks throughout—there’s no Linux or Windows port planned. If you’re developing on Linux or need cross-platform team compatibility, this immediately disqualifies cmux. The project’s GitHub discussions suggest the maintainers have no interest in Electron or cross-platform UI frameworks, viewing native performance as non-negotiable.
The deeper limitation is the dependency chain. cmux wraps libghostty, which itself is a relatively young terminal emulator (Ghostty reached 1.0 in late 2024). While Ghostty has excellent fundamentals, it doesn’t have decades of battle-testing like xterm or iTerm2. You’re betting on two projects instead of one, and inheriting bugs from both layers. The cmux issue tracker shows occasional rendering glitches and keybinding conflicts that stem from the Ghostty layer, which cmux maintainers can’t directly fix.
There’s also a learning curve investment. The scriptability is powerful but requires you to actually script your workflows. Unlike an IDE with built-in AI agent management (like Cursor or Windsurf), cmux gives you tools but no opinionated defaults. If you just want to run one AI agent occasionally, the vertical tabs and notification system are overkill—you’d be better served by Ghostty directly or even Terminal.app. The value proposition scales with workflow complexity.
Verdict
Use if: You’re a macOS developer running multiple AI coding agents in parallel and drowning in context-switching chaos. The visual notification system and scriptable workspace management will immediately improve your workflow, and the native performance means it won’t bog down your system like Electron alternatives. The investment in learning the CLI/socket API pays off quickly when you’re orchestrating complex multi-agent pipelines. Also use if you value Ghostty’s rendering performance but need workspace features that pure tmux doesn’t provide. Skip if: You’re on Linux/Windows, you only occasionally use AI coding tools (the complexity isn’t justified), you prefer the opinionated workflow of full IDE solutions like Cursor, or you’re deeply invested in tmux muscle memory and don’t want to learn new primitives. Also skip if you need a mature, battle-tested tool for production-critical work—cmux is impressive but still relatively young.
