How to Set Up cmux for Claude Code Teams on macOS in 2025

Why cmux for AI Coding Agents on macOS

If you're working with Claude Code Teams or other AI agents on macOS, managing terminal sessions traditionally means wrestling with tmux configuration files, complex keybindings, and splitting panes that don't visually represent your agent workflows.

cmux is a Ghostty-based terminal built specifically for AI agent workflows. Unlike generic terminal multiplexers, cmux provides native notification rings, vertical tabs showing git branches and PR status, and a sidebar that displays active listening ports and agent metadata—all without touching a single tmux config file.

This guide walks you through installing cmux, configuring it for Claude Code Teams, and optimizing it for multi-agent development workflows on macOS.

Prerequisites

Before starting, ensure you have:

• macOS 11 or later (Intel or Apple Silicon)
• At least 100 MB free disk space
• Claude Code installed (if using Claude Code Teams feature)
• Basic familiarity with terminal workflows

No prior Ghostty or tmux knowledge required—cmux handles the complexity internally.

Step 1: Download and Install cmux on macOS

The easiest way to get cmux running is via the official macOS installer:

1. Visit the cmux releases page and download the latest cmux-macos.dmg file
2. Open the DMG file by double-clicking it
3. Drag the cmux application into your Applications folder
4. Wait for the copy process to complete (usually 15–30 seconds)
5. Eject the installer by dragging the mounted volume to Trash

Once installed, cmux appears in your Applications folder and is automatically added to your system PATH. You can verify the installation:

which cmux
# Output: /Applications/cmux.app/Contents/MacOS/cmux

Step 2: Launch cmux and Create Your First Workspace

Launch cmux from Terminal:

cmux

On first run, cmux creates a default workspace and opens a split-pane terminal interface. You'll notice:

• A left sidebar showing vertical tabs
• A main terminal pane on the right
• No tmux status bar—all metadata is in the sidebar

Create a new workspace for a specific project:

cmux workspace my-project

This spawns a fresh terminal with a dedicated sidebar tab labeled "my-project." Each workspace maintains its own environment variables, working directory, and notification state.

Step 3: Enable Claude Code Teams Mode

The killer feature for AI agents: launch Claude Code Teams with a single command:

cmux claude-teams

This does three things automatically:

1. Spawns Claude Code's teammate mode as a native subprocess
2. Creates individual splits for each teammate agent (no manual pane creation)
3. Enables notifications so agent output triggers visual rings and sidebar badges

What you'll see:

• The sidebar now shows each teammate as a separate tab
• Each teammate tab displays:
  • Agent name (e.g., "researcher", "coder")
  • Current working directory
  • Active listening ports (if applicable)
  • Latest notification text (last 40 characters)
• A blue notification ring appears around the pane when an agent completes a task

Step 4: Configure Notifications and Focus

By default, cmux shows notification rings for all agent activity. To customize:

View All Pending Notifications

Click the notification panel icon in the top-right corner of the sidebar (looks like a bell with a badge). This shows:

• Unread notification count
• List of recent agent notifications
• Jump to most recent button

Customize Notification Behavior

Edit your cmux preferences file:

# macOS stores preferences in:
~/Library/Application\ Support/cmux/preferences.json

Add a notifications section:

{
  "notifications": {
    "enabled": true,
    "show_rings": true,
    "badge_unread_count": true,
    "auto_focus_on_activity": false
  },
  "sidebar": {
    "show_git_branch": true,
    "show_pr_status": true,
    "show_ports": true
  }
}

• auto_focus_on_activity: false prevents cmux from stealing focus when an agent finishes a task (useful if you're in another app)
• show_pr_status: true displays linked GitHub PR numbers and status in the sidebar

Step 5: SSH into Remote Machines (Multi-Agent Setup)

For distributed AI agent workflows, SSH into remote machines:

cmux ssh user@your-remote-host

This creates a dedicated workspace for the remote session where:

• All agent output routes through the remote (localhost bindings just work)
• Built-in browser panes route traffic through the remote network
• Drag-and-drop file uploads via scp (drag an image into the pane to upload)
• Notifications still fire locally so you see agent activity on your Mac

Step 6: Split Panes for Multi-Agent Monitoring

Manage multiple AI agents side-by-side:

Create Horizontal Split

Ctrl+B Ctrl+K  # macOS default keybinding

Or right-click the sidebar and select "Split Horizontally."

Create Vertical Split

Ctrl+B Ctrl+L  # macOS default keybinding

Or right-click and select "Split Vertically."

Pro tip: The sidebar always shows metadata for every pane—git branches, listening ports, and the last notification from each agent. This lets you scan all agent status without switching panes.

Step 7: Integrate cmux with Your Development Workflow

Launch cmux at Startup

Add to your ~/.zshrc or ~/.bash_profile:

# Open cmux on terminal launch (optional)
if [ -z "$CMUX_SESSION" ]; then
  export CMUX_SESSION=1
  exec cmux
fi

Use the Built-in Browser for Agent Web Tasks

Some AI agents need to browse web pages. cmux includes a scriptable in-app browser:

# Split the browser pane
cmux browser

The browser pane can be split horizontally or vertically alongside terminal panes. It supports:

• Cookies and authentication (persisted across sessions)
• Network routing through SSH remotes (localhost binding works)
• Scriptable API (agents can programmatically interact with the browser)

Common Configuration Pitfalls

Notification Rings Not Appearing

Problem: You don't see blue rings when agents complete tasks.

Solution: Ensure notification metadata is being passed from your agent. Claude Code Teams automatically sends notifications; custom agents need to write to stderr or use cmux's notification API.

Sidebar Metadata Missing

Problem: Git branch, PR status, or ports aren't showing.

Solution: Check preferences.json and ensure these are enabled:

{
  "sidebar": {
    "show_git_branch": true,
    "show_pr_status": true,
    "show_ports": true
  }
}

SSH Sessions Dropping

Problem: Remote workspace disconnects after inactivity.

Solution: Enable SSH keepalive in your ~/.ssh/config:

Host *
  ServerAliveInterval 60
  ServerAliveCountMax 10

Performance Tips for Large Workspaces

1. Limit simultaneous agents to 4–6 per workspace (cmux manages splits efficiently, but your shell's process limit matters)
2. Use separate workspaces for different projects—one workspace per project keeps notification noise low
3. Close unused notification rings manually by clicking the pane—this clears the visual indicator
4. Monitor listening ports via the sidebar to catch resource leaks early

Next Steps

Once cmux is running with Claude Code Teams:

• Explore the demo video on YouTube to see advanced workflows
• Read "The Zen of cmux" blog post on cmux.com for philosophy behind the design
• Join the Discord community to share agent workflows and get help
• Experiment with custom agents—cmux works with any CLI tool that outputs structured logs

Conclusion

cmux eliminates the learning curve of tmux while adding AI-specific features (notifications, agent metadata in the sidebar, Claude Code Teams integration). On macOS, it's the fastest way to go from "I need to run multiple AI agents" to "agents running with visual feedback." No config files, no keybinding memorization, just download the DMG and start working with your agents.