# 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:**
```command
cmux new-pane --type browser --url https://www.google.com
```
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:**
```command
cmux browser wait --surface surface:2 --load-state complete
```
**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:
```command
cmux browser snapshot --surface surface:2 --interactive
```
**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:**
```command
cmux browser type --surface surface:2 'e10' 'Hello World'
```
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:**
```command
cmux browser click --surface surface:2 'e14'
```
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:**
```command
cmux new-split right --workspace workspace:1
```
```command
cmux new-split down --workspace workspace:1 --surface surface:7
```
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:**
```command
cmux send --workspace workspace:1 --surface surface:7 "claude"
```
```command
cmux send-key --workspace workspace:1 --surface surface:7 "Return"
```
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:**
```command
cmux send --surface surface:7 "read and understand the project"
```
```command
cmux send --surface surface:8 "analyse the code of the project"
```
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:
```command
cmux notify --title "Analysis Complete" --body "Code review finished. Check pane for suggestions."
```
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:
```command
cmux trigger-flash --surface surface:8
```
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 [--icon ]`
Example: Let's say your project is on the `main` git branch. An agent can run:
```command
cmux set-status branch main --icon arrow.triangle.branch
```
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).
.