Stop Losing Track of AI Agents: cmux Is the Terminal Upgrade You Need

Your Claude Code session just went dark. Again.

You're running four agents in parallel—one refactoring your API layer, another writing tests, a third debugging that production incident, and somewhere in the chaos, Claude is waiting for your input with a notification that reads... "Claude is waiting for your input." No context. No clue which tab. Just another identical macOS banner in a sea of identical banners, while you frantically ⌘-Tab through seventeen Ghostty splits trying to find the one that actually needs you.

Sound familiar? If you're serious about AI-assisted development, you've hit the same wall every power user hits: the terminal wasn't built for agents. It was built for humans typing commands one at a time. But your workflow isn't human-linear anymore—it's parallel, asynchronous, and increasingly autonomous. You need a terminal that understands this new reality.

Enter cmux—the open-source, Ghostty-based macOS terminal that treats AI agents as first-class citizens. Not an orchestrator that locks you into someone else's workflow. Not another Electron memory hog. A native Swift/AppKit terminal with vertical tabs, intelligent notifications, an in-app browser, and a scriptable API that puts you back in control. Built by developers who were fed up with exactly what you're fed up with right now.

Ready to stop playing notification whack-a-mole? Let's dive deep into why cmux is becoming the secret weapon of developers running serious AI agent workloads.

What Is cmux? The Terminal AI Agents Actually Deserve

cmux is a free, open-source macOS terminal application developed by Manaflow AI, designed specifically around the needs of developers running multiple AI coding agents simultaneously. At its core, it's built on libghostty—the same GPU-accelerated rendering engine that powers Ghostty—meaning you get buttery-smooth terminal performance with full compatibility for your existing ~/.config/ghostty/config themes, fonts, and color schemes.

But calling cmux "just a terminal" misses the point entirely. It's a composable primitive for the agent-driven development era. The creators—who were themselves running massive parallel Claude Code and Codex sessions—identified a critical gap: existing terminals treat notifications as afterthoughts, splits as visual convenience, and browser integration as someone else's problem. cmux solves all three, natively.

The project launched to immediate developer enthusiasm, with its GitHub star history showing rapid organic growth driven entirely by word-of-mouth in AI engineering circles. What started as a personal productivity tool has evolved into a thriving open-source project with 18+ language translations, active Discord community, nightly builds, and a clear philosophical stance: give developers primitives, not prescriptions.

The "Zen of cmux" manifesto puts it bluntly: "Nobody has figured out the best way to work with agents yet, and the teams building closed products definitely haven't either." cmux doesn't pretend to have the answer. It gives you terminal, browser, notifications, workspaces, splits, tabs, and a CLI—then gets out of your way. This approach resonates deeply with developers who've been burned by opinionated orchestrators that promised productivity but delivered lock-in.

Key Features: The Technical Details That Matter

Notification Rings & Intelligent Attention Management

The flagship feature is context-aware notifications. When an agent needs you, cmux doesn't just fire a generic macOS banner. The target pane gets a visual blue ring, and the corresponding tab lights up in the sidebar with the actual notification text—not "Claude is waiting" but the real context. Hit ⌘⇧U to jump instantly to the most recent unread. No more hunting.

Under the hood, cmux listens for OSC 9/99/777 terminal sequences—the standard escape codes for terminal notifications—and exposes a cmux notify CLI that you can wire directly into agent hooks for Claude Code, OpenCode, Codex, and others. This means your agents can signal attention requirements with full semantic context, not just binary alerts.

Vertical Tabs with Rich Metadata

The sidebar displays git branch, linked PR status/number, working directory, listening ports, and latest notification text for each workspace. This transforms tab switching from memory-guessing into informed navigation. Split horizontally and vertically with standard shortcuts (⌘D for right split, ⌘⇧D for down split), and the metadata follows.

In-App Browser with Scriptable API

Split a browser pane alongside your terminal with ⌘⇧L. The browser isn't a toy—it's a scriptable automation surface with an API ported from Vercel's agent-browser. Agents can snapshot accessibility trees, get element references, click, fill forms, and evaluate JavaScript. Your Claude Code instance can literally interact with your dev server's UI without leaving the terminal context.

Native Performance, Zero Electron Tax

Built with Swift and AppKit, not Electron or Tauri. Startup is instant. Memory footprint stays low. GPU acceleration via libghostty ensures smooth rendering even with dense terminal output. This matters when you're running a dozen agent sessions and can't afford a framework tax on every render cycle.

SSH Workspaces with Network Tunneling

cmux ssh user@remote creates a dedicated workspace for remote machines. Browser panes automatically route through the remote network—localhost just works. Drag-and-drop image upload via SCP. It's the seamless remote development experience that should have existed years ago.

Claude Code Teams Integration

cmux claude-teams runs Claude Code's teammate mode as native splits with sidebar metadata and notifications. No tmux required. Each teammate spawns as a first-class pane with full cmux feature support, not a hacked-together subprocess.

Real-World Use Cases: Where cmux Shines

1. Parallel Agent Orchestration (The Core Problem)

You're running Claude Code on three microservices, Codex on the frontend, and OpenCode on infrastructure. Traditional terminals: 15 indistinguishable tabs, missed notifications, constant context loss. With cmux: each agent gets a workspace with visible git branch, PR status, and notification history. When service A's agent hits a dependency conflict, the blue ring and sidebar text tell you exactly where to look. ⌘⇧U teleports you there. Context preserved, time saved.

2. Full-Stack Development with Live Browser Interaction

Building a feature that spans API and UI? Split your terminal and browser with ⌘⇧L. Your agent writes the endpoint, switches to the browser pane, snapshots the accessibility tree, verifies the element renders, clicks through the flow—all without leaving cmux. The scriptable browser API means this isn't manual; it's automatable verification in your agent loop.

3. Remote Development Without Friction

SSH into your production debugging environment with cmux ssh prod-debug. Your local browser pane routes through the remote network automatically. Access internal dashboards at localhost:3000 as if you were local. Drag screenshots directly into terminal panes for SCP upload. The workspace saves with your session; reconnect tomorrow and everything restores.

4. Team-Based Agent Workflows with Claude Code Teams

Running Claude Code's teammate mode for complex multi-file refactors? cmux claude-teams spawns each teammate as a native split with independent notification streams. You see which teammate is blocked on input, which is still processing, which hit an error—all in the sidebar metadata. No tmux configuration archaeology required.

Step-by-Step Installation & Setup Guide

Method 1: DMG Download (Recommended)

The simplest path to get cmux running:

1. Download the latest release: Visit github.com/manaflow-ai/cmux/releases/latest/download/cmux-macos.dmg or click the macOS badge on the repository homepage.

2. Install: Open the .dmg and drag cmux to your Applications folder.

3. First launch: macOS may warn about an unidentified developer. Click Open to proceed.

4. Auto-updates enabled: cmux uses Sparkle for automatic updates—download once, stay current forever.

Method 2: Homebrew

For terminal-native developers who prefer package management:

# Add the cmux tap
brew tap manaflow-ai/cmux

# Install cmux
brew install --cask cmux

Update later with:

brew upgrade --cask cmux

Configuration: Ghostty Compatibility

cmux automatically reads your existing Ghostty configuration:

# Your existing Ghostty config works unchanged
cat ~/.config/ghostty/config
# Themes, fonts, colors all inherited

No migration needed. No duplicate configuration. Your carefully tuned Ghostty setup carries over seamlessly.

Agent Hook Installation

To enable session restore and smart notifications, install hooks for your agents:

# Install hooks for all detected agents
cmux hooks setup

# Or target specific agents
cmux hooks setup codex
cmux hooks setup --agent opencode

This wires cmux notify into your agent's lifecycle, enabling contextual notifications and resume-on-relaunch functionality.

Session Restore Configuration

Disable automatic agent resume if you prefer manual control:

# Create or edit cmux configuration
mkdir -p ~/.config/cmux
cat > ~/.config/cmux/cmux.json << 'EOF'
{
  "terminal": {
    "autoResumeAgentSessions": false
  }
}
EOF

Or toggle via Settings > Terminal > Resume Agent Sessions on Reopen.

REAL Code Examples from the Repository

Example 1: Agent Hook Setup Commands

The README provides exact commands for integrating cmux with your AI agents. These aren't theoretical—they're production-ready hooks:

# Install hooks for all supported agents cmux can detect
cmux hooks setup

# Target specific agents explicitly
cmux hooks setup codex
cmux hooks setup --agent opencode

What's happening here? The cmux hooks setup command inspects your PATH for supported agent binaries (Claude Code, Codex, OpenCode, Pi, Amp, Cursor CLI, Gemini, Rovo Dev, Copilot, CodeBuddy, Factory, Qoder, and more). For each detected agent, it installs shell integration hooks that bridge the agent's native notification system into cmux's OSC sequence handler. The --agent flag forces installation for a specific tool even if auto-detection misses it. After installation, when Claude Code needs input, it emits a terminal sequence that cmux intercepts—transforming a generic "waiting" message into a contextual sidebar notification with workspace metadata.

Example 2: Session Restore Configuration JSON

Control how cmux handles agent session resurrection:

{
  "terminal": {
    "autoResumeAgentSessions": false
  }
}

Deep dive: This configuration lives at ~/.config/cmux/cmux.json. When autoResumeAgentSessions is true (default), cmux rebuilds your workspace layout on relaunch, then executes each supported agent's native resume command—Claude Code's continue, Codex's resume, etc. The session mappings live in ~/.cmuxterm/ (written by agent hooks), while the layout snapshot versions itself in ~/Library/Application Support/cmux/. Setting this to false preserves layout restoration but keeps agent terminals idle, letting you choose when to manually resume with cmux restore-session or ⌘⇧O. This granular control matters for long-running agents you don't want auto-triggering on every launch.

Example 3: SSH Workspace with Network Tunneling

# Create a dedicated workspace for remote development
cmux ssh user@remote

The magic explained: This isn't just ssh in a new tab. cmux creates a workspace-scoped SSH session where browser panes automatically proxy through the remote network stack. Your localhost:8080 in a browser pane resolves to the remote's localhost, not yours. The drag-and-drop SCP upload works because cmux intercepts the drop event and routes it through the active SSH session's SFTP subsystem. When you quit cmux, this workspace's layout, working directory, and browser history serialize into your session snapshot. Relaunch, and the SSH workspace restores—though you'll need to reauthenticate (security first).

Example 4: Claude Code Teams Native Integration

# Launch Claude Code teammate mode as native cmux splits
cmux claude-teams

Why this matters: Without cmux, Claude Code Teams requires tmux or manual terminal management. Each teammate spawns as a subprocess you track mentally. With cmux, teammates become first-class panes with independent notification streams, sidebar metadata showing each teammate's status, and native split management. The integration is deep enough that Claude Code's wrapper (enabled in Settings) handles session resume automatically. No tmux configuration. No pane numbering schemes. Just cmux claude-teams and your team of agents materializes as a manageable, observable workspace.

Example 5: Manual Session Restore Trigger

# Reapply the last saved snapshot manually
cmux restore-session

When to use this: Even with auto-restore disabled, you sometimes need to resurrect a specific workflow. This command forces restoration of the versioned snapshot from ~/Library/Application Support/cmux/. It rebuilds window/workspace/pane layout, working directories, terminal scrollback (best effort), and browser URLs/history. Agent processes themselves don't checkpoint—tmux, vim, and shells reopen as fresh terminals—but the structural context you need to resume mentally is preserved. Combine with autoResumeAgentSessions: false for a "restore layout, decide when to restart agents" workflow that prevents accidental agent storms on relaunch.

Advanced Usage & Best Practices

Master the notification shortcuts. ⌘I opens the notification panel for global overview. ⌘⇧U jumps to latest unread—muscle memory this immediately. ⌥⌘U toggles read/unread state for triage. ⌃⌘U marks current and advances: perfect for batch-processing agent requests.

Browser import for authenticated sessions. Don't waste time logging into dev tools in browser panes. cmux imports cookies, history, and sessions from Chrome, Firefox, Arc, and 20+ browsers. Your authenticated state follows you.

Custom commands in cmux.json. Define project-specific actions that appear in the command palette. One keystroke to run your test suite, deploy script, or agent restart sequence. Documented at cmux.com/docs/custom-commands.

Script everything. The CLI and socket API expose workspace creation, pane splitting, keystroke injection, and browser automation. Build your own orchestration layer on top of cmux's primitives. This is the intended use case—the tool stays minimal, your workflow stays custom.

Run nightly alongside stable. The nightly build has a separate bundle ID, so both coexist. Test bleeding features without risking your daily driver.

Comparison with Alternatives

The verdict: cmux occupies a unique position. It's the only tool combining native performance, Ghostty compatibility, agent-native notifications, and scriptable browser integration without imposing workflow opinions. Electron orchestrators force their model; cmux gives you building blocks.

FAQ

Q: Is cmux free for commercial use? A: Yes, cmux is GPL-3.0-or-later and free forever. Organizations needing license flexibility can contact founders@manaflow.com for commercial licensing.

Q: Will cmux work with my existing Ghostty configuration? A: Automatically. cmux reads ~/.config/ghostty/config for themes, fonts, and colors. Zero migration effort.

Q: Which AI agents are supported for notifications and session restore? A: Claude Code, Codex, OpenCode, Pi, Amp, Cursor CLI, Gemini, Rovo Dev, Copilot, CodeBuddy, Factory, and Qoder—with more added based on community demand.

Q: Can I use cmux without AI agents? A: Absolutely. The agent features are additive, not required. Many users adopt cmux for vertical tabs, SSH workspaces, and native performance alone.

Q: How does cmux differ from using tmux with a browser? A: cmux eliminates tmux configuration complexity, provides native macOS notifications with context, integrates browser panes with automatic network routing, and restores sessions including browser state—not just terminal layout.

Q: Is there a Linux or Windows version? A: Currently macOS only. The Swift/AppKit foundation makes cross-platform non-trivial, though community interest is tracked for future evaluation.

Q: How do I get help or report issues? A: GitHub Issues, #nightly-bugs on Discord, or the active Reddit community. The maintainers are responsive and ship fast.

Conclusion: The Terminal Parallelization Demanded

The shift to AI-assisted development isn't incremental—it's a fundamental change in how developers interact with their tools. Running one agent occasionally? Your current terminal is fine. Running multiple agents in parallel, managing their attention demands, integrating browser verification, and maintaining context across sessions? That's a different problem requiring a different primitive.

cmux solves this without the bloat of Electron orchestrators or the configuration burden of tmux hacks. It's fast, native, open-source, and relentlessly focused on composability over prescription. The creators built it because they needed it. The growing community suggests you probably need it too.

The best part? You can validate this in minutes. Download the DMG, drag to Applications, and point it at your next Claude Code session. Feel the difference when notifications carry context, when tabs tell you what's happening, when your browser lives in the same workspace as your terminal.

Stop losing agents in the tab abyss. Start using cmux.

👉 Download cmux now from the official repository, star it if it saves you time, and join the Discord to shape where this goes next. The future of agent-driven development needs tools built by developers who actually live it—cmux is exactly that.