cmux: Native macOS Terminal for AI Coding Agents
cmux is a terminal built specifically for working with AI coding agents.
As AI-driven development grows, tools like Claude Code and OpenCode are becoming more capable. These agents can understand complex instructions, write code, and even debug their own work. But there is still a common problem. It is often hard to see what the agent is actually doing. Developers may not know why the agent is stuck, what step it is on, or what result it is working toward. This lack of visibility makes human-AI collaboration difficult.
cmux helps solve this problem. It is not just a place to run commands. It is an interactive workspace where AI agents can work more transparently. Agents can control browser windows, run multiple sub-agents in different panes, and send updates about their progress through notifications and UI changes.
In this article, we will look at how cmux works and why it is useful. You will learn the core ideas behind it and see practical examples from real use. You will also see how an AI agent can browse the web, create parallel agents to handle complex tasks, and keep you informed about what it is doing.
What is cmux? Understanding the core concepts
More than just a terminal: a native macOS experience
First, clearing up a common misconception: despite the similar name, cmux has absolutely nothing to do with the popular terminal multiplexer tmux. Instead of being a fork or a clone, cmux is a completely independent, native macOS application written in Swift and using AppKit.
Why is this important? Performance: As a native application, cmux is incredibly fast and lightweight. It leverages GPU acceleration for smooth rendering and avoids the overhead associated with cross-platform frameworks like Electron. Memory efficiency: Native apps are generally more memory-efficient. When you're running resource-intensive AI models, the last thing you want is your terminal itself consuming a large chunk of your system's RAM. Deep system integration: Being native allows for tight integration with macOS features, such as the notification system, which is a crucial part of the cmux feedback loop.
The technology stack: libghostty, WebKit, and Bonsplit
cmux is built on a solid foundation of powerful open-source libraries, each chosen for a specific purpose:
libghostty: This is the core terminal emulation library that powers cmux. It provides the fundamental functionality of a terminal, ensuring compatibility and robust performance. cmux also benefits from the ability to read and apply configurations directly from ghostty config files.
WebKit: For its powerful in-app browser functionality, cmux utilizes WebKit, the same browser engine that powers Apple's Safari. This provides a full-featured, standards-compliant browsing experience directly within a terminal pane, complete with access to developer tools.
Bonsplit: The flexible and intuitive layout system of tabs, panes, and splits is managed by a library called Bonsplit. This component is responsible for the smooth animations and drag-and-drop reordering that make managing complex workspaces a breeze.
This carefully selected stack allows cmux to offer a feature-rich environment without compromising on its core principles of speed and efficiency.
The communication backbone: the CLI and the Unix socket API
The true magic of cmux lies in how AI agents communicate with and control the application's user interface. This is achieved through a brilliant two-part system: a powerful Command Line Interface (CLI) and a high-speed Unix domain socket.
Here's how it works: an AI agent, running within a cmux pane, wants to perform an action (such as opening a new browser tab), the agent formulates and executes a shell command using the cmux CLI (e.g., cmux new-pane --type browser), this CLI command doesn't perform the action directly but instead sends a JSON-formatted message describing the requested action to a special file on the system called a Unix domain socket, and the main cmux application is constantly "listening" to this socket. When it receives the message, it interprets the command and updates the user interface accordingly.
A Unix domain socket is a form of Inter-Process Communication (IPC) that allows different programs on the same machine to exchange data with extremely low latency. By using this mechanism, cmux ensures that the communication between the agent (in its own process) and the terminal GUI is nearly instantaneous, creating a seamless and responsive experience.
Getting started with cmux
Getting up and running with cmux is straightforward. Once installed, you'll find a familiar yet powerful interface that serves as the foundation for agent-driven workflows.
Installation and initial setup
As a native macOS application, installation is simple. Navigate to the official cmux website (cmux.app), click the "Download for Mac" button to download the application disk image (.dmg), open the downloaded .dmg file, drag the cmux application icon into your Applications folder, and launch cmux from your Applications folder.
Upon first launch, cmux will also install its command-line tool, making the cmux command available in any shell running within the application.
A tour of the user interface
At first glance, cmux presents a clean, modern terminal interface. The key UI elements are: vertical tabs (sidebar) on the left side (a sidebar that functions as a vertical tab bar where your workspaces are listed), panes and splits (the main area can be divided into multiple panes with vertical or horizontal splits), and tabs within panes (each pane can also contain its own set of traditional horizontal tabs).
You can manipulate these elements manually using keyboard shortcuts, but the real power comes when you let an AI agent manage this layout for you.
Unleashing your AI agent: the cmux command line interface
The cmux CLI is the vocabulary your AI agent uses to speak to the terminal. By learning to use these commands, an agent can transform from a simple text-in, text-out tool into a dynamic actor that can manipulate its own environment.
Exploring the power of cmux help
The first command any agent (or human) should run is cmux --help. This provides a comprehensive list of all available commands and their options, serving as a complete reference manual for controlling the application.
The commands can be broadly categorized: workspace management (list-workspaces, new-workspace, rename-workspace), pane/surface management (new-split, new-pane, close-surface, trigger-flash), interaction commands (send sends text, send-key sends key presses like 'Return'), browser control (a whole suite of browser subcommands for navigation, interaction, and data extraction), and feedback and metadata (notify, set-status, set-progress, list-notifications).
An advanced agent can parse this help output to learn the full extent of its capabilities within the cmux environment.
Practical example: an agent-controlled browser session
Giving an agent the ability to browse the web is one of the most powerful features of cmux. In this scenario, an agent performs a Google search, a task that requires a sequence of distinct actions.
The prompt (natural language): "use the cmux cli to open the browser in a new pane, navigate to google.com, put 'Hello World' in the input, then click Google Search"
Command breakdown:
Open a browser pane:
The agent correctly identifies the need for a new pane. It uses the --type browser flag to specify that this pane should contain a WebKit browser, not another terminal shell. The --url flag instructs it to immediately navigate to Google's homepage.
Wait for the page to load:
A smart agent knows that it can't interact with a webpage before it has fully loaded. This command pauses the agent's execution until the browser reports that its loading process is complete.
Identify the target element (self-correction):
Initially, the agent might try a command that fails. The agent encounters an error and intelligently decides to get more information about its environment:
This is where the magic happens. The browser snapshot command returns a simplified, text-based representation of the current page's DOM. Crucially, it assigns short, unique references (like e10, e14) to interactive elements like links and input fields. The agent can now "see" the page structure.
Type into the search bar:
Armed with the information from the snapshot, the agent now knows that the search input field is identified by the reference e10. It uses this reliable reference to type the text "Hello World" into the search bar.
Click the search button:
Similarly, the agent finds the reference for the "Google Search" button in the snapshot (e14) and issues a click command on that specific element. The browser pane updates in real-time, showing the search results for "Hello World."
This entire sequence demonstrates a sophisticated workflow where the agent not only executes commands but also observes its environment, debugs failures, and adapts its strategy.
Advanced agent orchestration and parallelism
Complex software development tasks often require multiple streams of work to happen at once. cmux excels at this by allowing a primary agent to spawn and manage multiple "sub-agents," each working in its own dedicated pane.
The concept of sub-agents
Imagine you need to refactor a large piece of code. You could have a primary agent that orchestrates the process, but delegates specific tasks to specialized sub-agents: Sub-Agent 1 (Planner) runs in one pane to read the project requirements and break down the refactoring task into smaller steps, Sub-Agent 2 (Analyzer) runs in another pane to analyze the existing codebase, identifying dependencies and potential issues, and Sub-Agent 3 (Coder) once the plan is ready, this agent receives instructions to write the new code.
The primary agent can send instructions to each sub-agent, monitor their progress, and gather their results, all within a single, organized cmux workspace.
Creating and managing parallel agents
Breaking down how an agent can create two instances of itself to perform parallel analysis.
The prompt: "create 2 instances of claude each in their own new pane... use 1 instance... to read and understand the project, another instance to analyse the code... when they are done, read their output and close the panes"
Command breakdown:
Create split panes:
The agent first splits the window to the right, creating a new surface (surface:7). It then splits that new surface down, creating another one (surface:8). It now has three panes in total.
Launch sub-agents:
The send command types the text "claude" into the specified pane, and send-key simulates pressing the Enter key. This launches a new, independent instance of the Claude Code agent in each of the new panes.
Assign tasks:
The primary agent now sends the specific, distinct instructions to each sub-agent by targeting their unique surface IDs. The two sub-agents begin working on their tasks in parallel.
Await completion and gather results:
After the sub-agents finish, the main agent would use commands like cmux read-screen --surface surface:7 to capture the output from each pane. It then uses cmux close-surface --surface surface:7 and cmux close-surface --surface surface:8 to clean up the workspace.
This powerful parallel processing capability allows agents to tackle much larger and more complex problems than they could alone.
Creating a rich feedback loop: notifications and sidebar customization
A key aspect of effective human-AI collaboration is communication. cmux provides multiple channels for an agent to get your attention and provide you with at-a-glance status updates.
Never miss an update: using notifications and flashes
When an agent is running a long task in the background, you might switch to another workspace. cmux ensures you're alerted when the agent needs you.
System notifications (notify): An agent can use the cmux notify command to send a standard macOS system notification:
This notification will appear even if cmux is not the active application. Clicking on it will instantly focus cmux and take you to the relevant workspace.
Visual flashes (trigger-flash): For a more immediate, in-app alert, an agent can use the trigger-flash command:
This command causes a bright blue border to flash around the specified pane, visually drawing your attention to the exact location that needs input.
Customizing the sidebar for at-a-glance information
The vertical tab bar on the left is more than just a list of workspaces; it's a dynamic status board that agents can write to.
Command: cmux set-status <key> <value> [--icon <sf_symbol_name>]
Example: Let's say your project is on the main git branch. An agent can run:
Result: The sidebar entry for the current workspace will be updated to show the text "main" next to a git branch icon.
This feature is incredibly versatile. Agents can use it to display the current git branch, the status of running tests, the progress of a long-running build, or the name of the file currently being edited.
Combined with the set-progress command, which displays a progress bar in the sidebar, these tools provide a rich, ambient awareness of what all your agents are working on at any given time.
Integrating cmux with your favorite AI agent
Because cmux is controlled via a universal CLI, it is fundamentally agent-agnostic. Any agent or tool that can execute shell commands can be integrated with cmux. However, there are a few practical considerations to ensure a smooth experience.
A note on sandboxing
Many modern AI agents, including Claude Code, run commands in a "sandbox" for security reasons. This sandbox can sometimes prevent the agent from accessing the cmux Unix socket at its default location (/tmp/cmux.sock). If you see an error like "Failed to connect to socket," you may need to configure your agent to disable its sandbox.
While this provides the agent with the full power of cmux, be aware of the security implications of allowing an AI to run commands outside of a sandboxed environment.
Using Claude Code hooks for seamless integration
For an even deeper integration, cmux provides a hook system for Claude Code. This allows you to create scripts that are automatically triggered by agent events, such as when a session starts or a task completes. This is perfect for automating notifications without having to explicitly ask the agent to send them each time.
Final thoughts
cmux represents a significant step forward in the field of human-computer interaction for AI-driven development. By providing a performant, observable, and controllable environment, it tears down the "black box" and transforms AI agents from opaque tools into transparent collaborators.
You've seen its core architecture, from its native macOS foundation to its fast Unix socket communication layer. You've witnessed its power in action through practical examples: orchestrating a web browsing session with self-correcting logic, managing parallel sub-agents to divide and conquer complex tasks, and creating a rich feedback loop with system notifications and a dynamic sidebar.
The true strength of cmux is that it provides a universal language (a simple yet powerful CLI) that any agent can learn to speak. This empowers developers to integrate cmux into their existing workflows with any agent harness they choose. While the initial setup of hooks and skills can be manual, the foundation is incredibly solid. cmux is not just another terminal; it is a dedicated platform for the next generation of software development, where human ingenuity and artificial intelligence work side-by-side in a shared, visible, and interactive space. If you are serious about leveraging AI coding agents, exploring cmux is not just recommended (it's essential).
.
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.