Introduction to cmux: A macOS Terminal for AI Coding Agents

What is cmux?

cmux is a macOS-native GPU-accelerated terminal. Based on Ghostty's rendering engine (libghostty), it adds specialized features for collaborating with AI coding agents.

Built with Swift and AppKit, it is free and open-source (AGPL-3.0).

The Limits of IDE Terminals

While using Claude Code within Cursor or VS Code has been the mainstream, full-scale multi-agent operations eventually hit a wall.

• Memory Consumption: VS Code with 2 windows + Claude Code consumes over 8GB of RAM. A Ghostty-based terminal consumes less than 500MB under the same conditions.
• Multi-Agent: IDEs are designed for a "one project, one window" workflow. Opening five IDEs to run five agents in parallel is not practical.
• Scriptability: Pipe integrations like git diff | claude "review this" are impossible within an IDE.

Given this background, high-speed native terminals like Ghostty have gained attention, leading to the emergence of cmux, which includes features specifically for AI agents.

Why cmux?

Even when moving outside of an IDE, existing terminals (like iTerm2 or standalone Ghostty) have their own challenges:

• Hard to track which agent is running in which tab.
• Unaware when an agent is waiting for input.
• Complicated switching between development servers and browsers.

cmux solves these with the following features:

• Notification Rings: A blue ring appears on a pane when an agent is waiting for input.
• Vertical Tab Sidebar: Lists Git branches, PR statuses, port numbers, and the latest notifications.
• Built-in Browser: Splits the terminal screen to display a browser alongside it.

Installation

DMG (Recommended)

Download the .dmg from the official website or GitHub Releases and drag it to Applications. It supports automatic updates via Sparkle, so once you install it, you are all set.

Homebrew

brew tap manaflow-ai/cmux
brew install --cask cmux

If you are a Ghostty user, your existing settings in ~/.config/ghostty/config will be inherited automatically.

Basic Operation

Shortcut List

Operation	Key
New Workspace	⌘ N
Split Right	⌘ D
Split Down	⌘ ⇧ D
Open Browser	⌘ ⇧ L
Notification Panel	⌘ I
Jump to Unread	⌘ ⇧ U
Next Surface	⌃ Tab

Workflow Example: Claude Code × cmux

Let's assume a case where you are developing a frontend and a backend in parallel.

Step 1: Create a workspace with ⌘ N.

Step 2: Split the pane to the right with ⌘ D. Start claude on the left (frontend) and start claude on the right (backend).

Step 3: Add a pane below with ⌘ ⇧ D and start the development server with npm run dev.

Step 4: Open the browser with ⌘ ⇧ L to preview localhost:3000.

When an agent is waiting for input, a blue ring glows, so you won't miss it even when running multiple sessions.

Automation: CLI and Socket API

cmux comes with a CLI and a Socket API (via /tmp/cmux.sock), allowing you to automate everything from pane operations to inter-agent communication.

Notification Integration: Combine the Claude Code Stop hook with cmux notify to light up the notification ring when an agent finishes a task.

cmux notify --title "Claude Code" --body "Task complete" --level info

Inter-agent Communication: You can inject text directly into an agent in another pane using cmux send. Multi-agent collaboration, such as Claude Code on the left pane (design lead) to Codex on the right pane (implementation lead), is also possible. This is still an experimental feature but is highly noteworthy.

cmux identify --json                      # Confirm your current position
cmux send --surface surface:4 "Review this"  # Send to another pane
cmux send-key enter                        # Send Enter

Automating Environment Setup: An example of building a per-branch workspace in one go by combining it with git worktree:

git worktree add -b my-branch ../repo-my-branch
ws=$(cmux new-workspace 2>&1 | awk '{print $2}')
cmux send --workspace "$ws" "cd ../repo-my-branch && claude"
cmux send-key --workspace "$ws" Enter

Built-in Browser vs. Playwright

cmux's browser features an API ported from Vercel Labs' agent-browser, allowing for snapshots, element clicking, form entry, and JS execution.

While the types of operations are similar to Playwright, the design philosophy differs.

	cmux Browser	Playwright
Approach	Snapshot + Refs (returns only actionable elements)	Entire accessibility tree
Token Efficiency	High (up to 93% reduction)	Low (approx. 114K tokens via MCP)
Setup	Built-in to cmux, no extras required	Requires separate MCP or CLI
Cross-browser	Not supported	Chrome / Firefox / Safari
CI/CD	Not supported	Supported

It is practical to use the token-efficient cmux browser for UI checks during development, and Playwright for pre-production testing.

The "No File Tree" Problem

While you might feel uneasy about the lack of a VS Code sidebar, it can be solved in practice through the following patterns:

1. Ask the Agent: Simply instruct it with "Show me the contents of src/auth," and Claude Code will list the files and their contents. This drastically reduces the frequency of searching manually.

2. Keep Neovim Open Next to It: Split the cmux pane to put Claude Code on the left and Neovim + a file tree plugin (like neo-tree) on the right. Move between panes with Ctrl+h/l.

3. Use the IDE Only for Code Reviews: Let the agents on cmux handle code editing and generation, and perform manual source verification only during PR reviews. Use the GitHub diff view or VS Code/Cursor to check changes and provide feedback to the agents.

The common thread is that "AI agents handle file operations for you, so the frequency of manually searching for files itself decreases significantly."

Points of Caution

Conflict with Security Software

In environments where security software like Microsoft Defender is running, cases may occur where ls or cd in Ghostty/cmux result in an Interrupted system call error.

$ ls ~/Documents
ls: .: Interrupted system call    # Occurs in macOS protected directories

$ ls ~/go
bin  pkg  src                     # User-created directories are fine

This is caused by a conflict between libghostty's PTY processing and the security software's file access monitoring, which interrupts system calls.

Solution:

1. Add cmux to System Settings → Privacy & Security → Full Disk Access.
2. Configure your security software to exclude cmux/Ghostty from scanning.

This is particularly common on Macs managed by companies, so if you find that ls isn't working, suspect this first.

Backspace Not Working During SSH Connections

When connecting via SSH from cmux, you may encounter a phenomenon where backspace does not delete characters and instead appears to add spaces (GitHub Issue #674).

cmux sets TERM=xterm-ghostty, but if this terminfo is missing on the SSH destination, the shell's echo processing breaks. This does not affect TUI apps like Claude Code, but occurs with line editing in bash/zsh.

Solution: Add the following to ~/.bashrc / ~/.zshrc on the SSH destination.

# cmux (Ghostty) SSH workaround
case "$TERM" in
  xterm-ghostty*) export TERM=xterm-256color ;;
esac

Others

• macOS Only: Linux/Windows not supported.
• Session Restoration Limit: Window layout is restored, but live processes like Claude Code are not.
• Ghostty Setting Compatibility: Themes, fonts, and colors are inherited as-is, but some Ghostty-specific settings may not be supported.

Summary

📝 The complete version of this article (details on CLI/Socket API, comparison table with Playwright, etc.) is available in the ZenChAIne media article.

cmux is a tool that embodies the "terminal for the AI agent era." If your development style involves running multiple Claude Code sessions, the notification ring and sidebar alone will drastically change your productivity.

With one-line installation via Homebrew and support for inheriting Ghostty settings, the cost of trying it out is low. If you're interested, please give it a try.