Stop Losing Context! cmux Is the Terminal AI Agents Actually Need

You've got six Claude Code sessions running. Three are indexing repositories, two are running tests, and one just hit a permissions error that needs your immediate attention. But which one? You cmd+tab through a sea of identical Ghostty windows, squinting at truncated tab titles, praying you don't kill the wrong process. Meanwhile, that critical agent notification? Buried under macOS's generic "Claude is waiting for your input" banner with zero context about which project, which branch, what went wrong.

Sound familiar? This is the silent productivity killer nobody talks about in the AI coding revolution. We're all racing to spin up more agent sessions, orchestrate parallel workflows, and squeeze every drop of efficiency from Claude, Codex, and their cousins. But our terminals? Stuck in 1984. Horizontal tabs that disappear into oblivion. Notifications that treat context as optional. No integration between what your agent sees in the browser and what you're typing in the terminal.

Enter cmux — a Ghostty-based macOS terminal that doesn't just acknowledge the AI agent era, it's built for it. Vertical tabs with live git branch and PR status. Blue notification rings that tell you exactly which pane needs attention. An in-app browser your agents can actually interact with. And it's all native Swift/AppKit, not another Electron memory hog. Ready to stop context-switching and start context-preserving? Let's dive into why cmux is about to become the most important tool in your AI development arsenal.

What is cmux?

cmux is an open-source macOS terminal application built on top of Ghostty's rendering engine, created by Lawrence Chen and Austin Wang under the Manaflow AI umbrella. Born from a very specific frustration — running multiple Claude Code sessions simultaneously and losing track of which agent needed human intervention — cmux transforms the terminal from a passive text conduit into an active orchestration layer for AI-assisted development.

The project launched publicly in early 2025 and has been gaining explosive traction among developers who've hit the same wall: traditional terminals simply weren't designed for a world where a single developer might have 5-10 AI agents working in parallel across different repositories, branches, and environments. While tools like tmux and terminal multiplexers offer basic session management, they don't speak "agent." They don't surface notification context. They don't integrate browsers that your AI can see and manipulate.

cmux fills this gap by reading your existing ~/.config/ghostty/config for themes, fonts, and colors — so your aesthetic investment transfers seamlessly — then layers on agent-aware primitives: a sidebar with vertical tabs showing real-time workspace metadata, a notification system that understands OSC terminal sequences and agent hooks, an embeddable scriptable browser, and a comprehensive CLI/socket API for automation. It's free, GPL-3.0 licensed, with a commercial license available for organizations that need it.

The philosophy behind cmux is deliberately anti-prescriptive. As the creators state: "cmux is a primitive, not a solution." It gives you composable building blocks — terminal, browser, notifications, workspaces, splits, tabs, CLI control — and trusts that you'll build workflows more efficiently than any top-down product team could design. In an era where every VC-backed startup is trying to lock you into their "AI IDE," cmux's agnosticism feels almost radical.

Key Features That Separate cmux from the Pack

Notification Rings & Intelligent Alerting

When an AI agent triggers a notification via OSC 9/99/777 sequences or the cmux notify CLI, the target pane receives a distinctive blue ring border. The corresponding vertical tab in the sidebar illuminates with the latest notification text. No more guessing which of twelve tabs needs you. The Cmd+Shift+U shortcut jumps directly to the most recent unread, and a dedicated notification panel (Cmd+I) aggregates all pending alerts with full context.

Vertical Tabs with Live Metadata

cmux's sidebar isn't decorative. Each vertical tab displays: current git branch, linked PR status and number, working directory, listening ports, and the latest notification text. This transforms tab switching from memory-guessing into informed navigation. Split horizontally and vertically while maintaining full situational awareness.

In-App Scriptable Browser

Ported from Vercel's agent-browser project, cmux embeds a full browser with programmatic API access. Agents can snapshot accessibility trees, obtain element references, execute clicks, fill forms, and evaluate JavaScript. Split browser panes alongside terminals so Claude Code can interact with your dev server directly — no more context destruction from alt-tabbing to Chrome.

Native Performance, Zero Electron Tax

Built with Swift and AppKit, cmux launches instantly and sips memory. GPU-accelerated rendering via libghostty ensures smooth scrolling even with heavy terminal output. Browser panes route through remote networks during SSH sessions so localhost resolution works transparently.

Seamless Ghostty Compatibility

Your existing ~/.config/ghostty/config — themes, fonts, colors, key bindings — works out of the box. No migration friction, no configuration rewrites. cmux extends Ghostty rather than replacing it.

Comprehensive Session Restoration

Quitting cmux snapshots window/workspace/pane layout, working directories, terminal scrollback (best effort), and browser URL/history. Supported agent sessions resume via native hooks for Claude Code, Codex, OpenCode, Pi, Amp, Cursor CLI, Gemini, Rovo Dev, Copilot, CodeBuddy, Factory, and Qoder.

Browser Import Ecosystem

Import cookies, history, and sessions from Chrome, Firefox, Arc, and 20+ additional browsers. Your browser panes start authenticated — no manual login dance for every new session.

Real-World Use Cases Where cmux Dominates

Parallel Agent Orchestration

You're leading a refactor across three microservices. Claude Code instance A handles the API gateway, instance B migrates the database layer, instance C updates the frontend contracts. Previously, you'd need three terminal windows, constant manual checking, and a notepad to track status. With cmux, each instance gets a vertical tab showing branch (refactor/api-v2, refactor/db-migration, refactor/contract-sync), PR status, and notification state. When instance B hits a schema conflict, its tab lights up blue with the error context visible — you context-switch with precision, not panic.

Full-Stack Development with Agent Browser Integration

Your agent needs to verify that a backend change renders correctly in the UI. In traditional workflows, you'd stop the agent, open Chrome, navigate to localhost:3000, check manually, return to terminal. With cmux, split a browser pane (Cmd+Shift+L) alongside your terminal. The agent snapshots the accessibility tree, confirms the element exists, reports success — all without leaving the workspace. The browser routes through SSH remotes automatically, so localhost:3000 on a deployed dev server resolves as expected.

Remote Development with Native SSH Workspaces

Run cmux ssh user@remote and cmux constructs a complete workspace for that machine. Browser panes route through the remote network transparently. Drag-and-drop image upload via SCP works intuitively. Your local vertical tabs track remote git branches and PRs with the same fidelity as local projects. The notification system bridges SSH boundaries — an agent waiting on the remote machine surfaces identically to local ones.

Claude Code Teams Without tmux Complexity

Execute cmux claude-teams to launch Claude Code's teammate mode. Each teammate spawns as a native split with sidebar metadata and notification integration. No tmux configuration, no pane management arcana, no notification duct-taping. Teammates become first-class citizens in cmux's workspace model rather than afterthoughts in a multiplexer.

Step-by-Step Installation & Setup Guide

Method 1: DMG Download (Recommended)

The simplest path for most users:

# Download directly from GitHub releases
curl -L -o cmux-macos.dmg https://github.com/manaflow-ai/cmux/releases/latest/download/cmux-macos.dmg

Open the .dmg, drag cmux to your Applications folder. That's it — cmux auto-updates via Sparkle, so this one-time installation stays current automatically.

On first launch, macOS Gatekeeper will request confirmation for an unidentified developer. Click Open to proceed.

Method 2: Homebrew

For terminal-first developers who prefer package management:

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

# Install cmux as a Cask
brew install --cask cmux

Future updates follow standard Homebrew patterns:

brew upgrade --cask cmux

Post-Installation Configuration

cmux automatically reads your Ghostty configuration:

# Verify your existing config is detected
cat ~/.config/ghostty/config
# Themes, fonts, colors transfer seamlessly

Create cmux-specific configuration for advanced features:

mkdir -p ~/.config/cmux

Example ~/.config/cmux/cmux.json for custom commands:

{
  "terminal": {
    "autoResumeAgentSessions": true
  },
  "customCommands": [
    {
      "name": "Deploy Staging",
      "command": "npm run deploy:staging",
      "shortcut": "cmd-shift-s"
    }
  ]
}

Agent Hook Installation

Enable session restoration for your AI agents:

# Install hooks for all detected agents
cmux hooks setup

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

The cmux hooks setup command auto-detects installed agents and prints a summary. Supported integrations include Claude Code, Codex, OpenCode, Pi, Amp, Cursor CLI, Gemini, Rovo Dev, Copilot, CodeBuddy, Factory, and Qoder.

Nightly Builds

For bleeding-edge features and early bug fixes:

curl -L -o cmux-nightly-macos.dmg https://github.com/manaflow-ai/cmux/releases/download/nightly/cmux-nightly-macos.dmg

Nightly builds use a separate bundle ID, so they run alongside stable cmux without conflict. Report issues on GitHub or in #nightly-bugs on Discord.

REAL Code Examples from cmux

Example 1: Agent Notification via CLI

The cmux notify command is the bridge between your AI agents and cmux's visual notification system. Wire this into agent hooks for immediate integration:

# Send a notification with context to a specific workspace
cmux notify --workspace "api-gateway-refactor" \
  --title "Schema Validation Failed" \
  --body "Foreign key constraint violated on users.id"

# The pane for "api-gateway-refactor" now shows:
# - Blue notification ring around the pane border
# - Illuminated tab in sidebar with "Schema Validation Failed"
# - Full message visible in notification panel (Cmd+I)

This replaces the useless "Claude is waiting for your input" with actionable context. The --workspace parameter targets specific sessions, so parallel agents don't create notification noise for each other.

Example 2: SSH Workspace Creation

Remote development becomes first-class with cmux's SSH integration:

# Create a complete workspace for remote development
cmux ssh deploy@production-api.internal

# Effects:
# - New workspace with vertical tab showing remote hostname
# - Browser panes route through remote network (localhost resolves remotely)
# - Drag images into terminal for automatic SCP upload
# - Git branch and PR metadata fetched from remote working directory
# - Notifications from remote agents surface identically to local ones

The network routing is particularly subtle and powerful. Traditional SSH terminal sessions force you to maintain mental models of port forwarding (-L 8080:localhost:8080). cmux's browser panes handle this transparently — your agent can reference http://localhost:3000 and it resolves against the remote machine's network context.

Example 3: Claude Code Teams Launch

Eliminate tmux complexity for multi-agent Claude sessions:

# Launch Claude Code teammate mode with native cmux integration
cmux claude-teams

# Each teammate spawns as:
# - Native split pane (not tmux window/pane)
# - Sidebar entry with independent git branch tracking
# - Independent notification ring and tab illumination
# - Shared workspace context without shared terminal state

Compare to manual tmux setup: no .tmux.conf editing, no pane synchronization configuration, no notification forwarding scripts. The claude-teams subcommand handles workspace creation, split management, and hook registration in one operation.

Example 4: Session Hook Configuration

Fine-tune agent session restoration behavior:

# ~/.config/cmux/cmux.json
{
  "terminal": {
    // Disable automatic agent resume on relaunch
    // Keeps restored terminals idle instead of running resume commands
    "autoResumeAgentSessions": false
  }
}

With autoResumeAgentSessions: false, cmux still restores layout, working directories, scrollback, and browser history — but agent terminals remain idle. This prevents unintended side effects when you're reopening cmux to investigate rather than continue execution. Toggle via Settings > Terminal > Resume Agent Sessions on Reopen or the JSON configuration above.

Manual session restoration remains available:

# Reapply last saved snapshot on demand
cmux restore-session

Example 5: Browser Automation API

The scriptable browser API enables agent-driven web interaction:

// Executed within cmux browser pane context
// Snapshot accessibility tree for agent consumption
const tree = await cmux.browser.snapshotAccessibility();

// Obtain stable element reference
const submitButton = await cmux.browser.querySelector({
  role: 'button',
  name: /submit/i
});

// Perform agent-directed interaction
await submitButton.click();
await cmux.browser.evaluate(`
  // Custom validation logic
  window.validateFormState()
`);

This API, ported from Vercel's agent-browser, runs within cmux's embedded browser rather than requiring external Chrome/Chromium instances. The accessibility tree snapshot provides semantic structure that raw HTML parsing misses — crucial for agents navigating complex SPAs.

Advanced Usage & Best Practices

Workspace Naming Conventions

Establish consistent workspace names that encode project and purpose: service-name/task-type. This maximizes sidebar information density. Combine with Cmd+Shift+R for rapid renaming as contexts shift.

Notification Prioritization Patterns

Configure agent hooks to send cmux notify with severity-encoded titles. Use prefixes like [BLOCKED], [REVIEW], [DONE] to enable visual scanning of the notification panel without expanding each entry.

Browser Pane Layouts

Develop muscle memory for Cmd+Shift+L (browser in split) versus Cmd+L (focus address bar). The former creates new browser surfaces; the latter navigates existing ones. For API development, maintain a vertical split with terminal left, browser right, both in the same workspace.

Custom Commands for Repetitive Workflows

Define project-specific actions in cmux.json that appear in the command palette. Deployment scripts, test runners, linting — all accessible via searchable palette rather than shell history archaeology.

Session Restoration Hygiene

Periodically run cmux restore-session manually to verify snapshot integrity. The automatic restoration is best-effort for scrollback; critical output should be logged to files or captured via script command.

Comparison with Alternatives

cmux occupies a unique position: it combines Ghostty's rendering performance with AI-agent-specific features that no other terminal offers natively. Unlike Warp's closed-source, cloud-dependent model, cmux keeps everything local and transparent. Unlike tmux-based solutions, it requires zero configuration for sophisticated agent orchestration.

FAQ

Is cmux free for commercial use?

cmux is GPL-3.0-or-later licensed, free for personal and commercial use under those terms. Organizations unable to comply with GPL can contact founders@manaflow.com for commercial licensing.

Does cmux work with my existing Ghostty configuration?

Yes — cmux reads ~/.config/ghostty/config directly for themes, fonts, colors, and key bindings. No migration needed.

Which AI agents are supported for notifications and session restore?

Claude Code, Codex, OpenCode, Pi, Amp, Cursor CLI, Gemini, Rovo Dev, Copilot, CodeBuddy, Factory, and Qoder. New agents are added based on community demand.

Can I use cmux without AI agents?

Absolutely. The notification system works with any tool emitting OSC 9/99/777 sequences or invoking cmux notify. Many features — vertical tabs, browser integration, SSH workspaces — provide value regardless of agent usage.

How does cmux compare to terminal multiplexers like tmux?

cmux replaces tmux for most users by providing native splits, session restoration, and agent integration without configuration complexity. Advanced tmux users with heavily customized setups may run both, though cmux's native primitives reduce the need.

Is there a Linux or Windows version?

cmux is currently macOS-only due to its Swift/AppKit foundation. The roadmap includes cross-platform expansion; follow @manaflowai for updates.

How do I report bugs or request features?

Use GitHub Issues for bugs, GitHub Discussions for feature requests, or join the Discord for real-time community support.

Conclusion

The AI coding revolution isn't coming — it's here, and our tools are embarrassingly unprepared. We've accepted context destruction as inevitable: alt-tabbing into oblivion, generic notifications with zero relevance, browser terminals that exist in separate universes. cmux rejects this resignation entirely.

What impresses most about cmux isn't any single feature, though the notification rings and vertical tabs are genuinely transformative. It's the philosophical coherence: composable primitives over prescriptive workflows, native performance over Electron convenience, open extensibility over vendor lock-in. Lawrence Chen and Austin Wang built the terminal they needed for their own agent-heavy workflows, then open-sourced it with a clarity of purpose that resonates.

If you're running multiple AI agents, struggling with context fragmentation, or simply ready for a terminal that understands how modern development actually works, cmux demands your attention. Download the latest release from GitHub, install via Homebrew, or grab the nightly build if you're feeling adventurous. Your future self — the one managing eight parallel agent sessions without breaking a sweat — will thank you.

The best developers build their own tools. With cmux, you don't have to start from scratch.