cmux

“The terminal built for multitasking, organization, and programmability.” A free, open-source, native macOS terminal built on Ghostty — designed for developers who run many AI coding agents (Claude Code, Codex, Gemini CLI, OpenCode, Amp, Aider…) side by side and need to know which one needs attention right now.

All facts verified against the linked sources on 2026-07-09. cmux moves fast (multiple releases per week) — cross-check the changelog for anything newer.

The problem it solves

Coding agents turned the terminal into a fleet-management surface: you're no longer typing into one shell, you're supervising five to fifty long-running sessions. Classic terminals (and tmux) give you panes, but no way to see at a glance which session finished, which is blocked waiting for input, and which broke. cmux's answer is to make the terminal itself agent-aware:

• Notification rings — a blue ring appears on the exact pane whose agent needs attention, aggregated in a panel with jump-to-latest-unread shortcuts.
• Vertical tabs (workspaces) — a sidebar showing each session's git branch, PR status, working directory, listening ports, and latest notification.
• Embedded scriptable browser — agents can open a real browser split next to their terminal to visually verify what they built.
• CLI + socket API — every workspace, pane, and keystroke is programmable, so agents can drive cmux itself.

Vital statistics

Sources: cmux.com · GitHub README · HN Algolia · Ry Walker research note

2 · History & the pivot

“cmux” has meant two different products from the same team — important to know, because older articles and videos describe a tool that no longer carries the name.

The old cmux (2025): containerized orchestrator

The original cmux let you fan one task out to multiple coding agents (Claude Code, Codex CLI, Cursor CLI, Gemini CLI, Amp, Opencode) simultaneously, each in its own isolated VS Code workspace running in a local Docker container or in the cloud. When all runs finished, a built-in “Crown” evaluator compared the outputs and marked the best one. That product line continues as manaflow-ai/manaflow, described as an “open source Claude Code web / Codex Cloud / Devin / Ramp Inspect alternative.”

Why the pivot to a terminal

The team's stated reasoning: most orchestrators are Electron/Tauri apps whose performance disappointed them, and GUI orchestrators lock you into their workflow. A terminal is the workflow-neutral primitive — so they built a native Swift/AppKit app on a fork of Ghostty's GPU-accelerated libghostty core, and made observability (notifications) and programmability (socket API) the product.

Sources: manaflow repo · ScriptByAI on the orchestrator · Ry Walker research note · HN Algolia

3 · Mental model: the five-level hierarchy

Everything in cmux hangs off one containment chain. Learn this and the whole keyboard/CLI surface becomes predictable:

Window → Workspace → Pane → Surface → Panel

Source: docs/concepts · docs/workspace-groups

4 · Architecture internals

cmux is a native Swift/AppKit application that embeds libghostty as a rendering library — the way apps embed WebKit. Around that core it adds an AppKit UI shell, a WebKit browser surface type, a notification engine fed by terminal escape sequences, a state snapshot store, and a JSON control plane over a Unix socket.

Design choices worth remembering

• Escape sequences as a first-class channel. Notifications ride the terminal protocol itself (OSC 9/99/777), so any program in any pane can raise pane-addressable alerts — no SDK needed.
• Terminals all the way down. The terminal an agent drives can itself contain another agent — real, addressable terminals rather than an SDK abstraction over hidden processes.
• Socket security by ancestry. Default mode only lets cmux child processes connect; allowAll opens it to any local process (opt-in).
• Session restore restores layout, not computation. Windows, workspaces, panes, directories, and scrollback come back after relaunch — but arbitrary process state (a tmux or vim session) is not checkpointed.

Sources: GitHub README · docs/api · docs/session-restore · docs/ssh

5 · Install & setup

Requirements: macOS 14.0+ (Apple Silicon or Intel).

1. Install the app — either download the DMG from cmux.com (auto-updates via Sparkle), or:

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

2. Link the CLI so scripts and agents outside cmux can reach it:

   sudo ln -sf "/Applications/cmux.app/Contents/Resources/bin/cmux" /usr/local/bin/cmux

3. Verify — launch: you should see the vertical-tab sidebar, one active workspace, and a Ghostty-powered terminal. Then cmux ping from a pane.
4. Optional: teach your agents cmux — install the official skills so Claude Code & co. know the CLI:

   npx skills add manaflow-ai/cmux -g -y
   # or the simpler script:
   curl -fsSL https://raw.githubusercontent.com/manaflow-ai/cmux/main/skills.sh | bash

5. Optional: keep your Ghostty look — cmux reads ~/.config/ghostty/config automatically; existing themes and fonts just apply.

Sources: docs/getting-started · docs/skills

6 · Core workflows

Workflow 1 — Run agents in parallel, one workspace each

1. ⌘N new workspace per task/repo (or ⌘O to open a folder). Rename with ⌘⇧R; the sidebar shows branch, PR status, cwd, and ports automatically.
2. Launch an agent in each: claude, codex, opencode — any CLI agent works, cmux is agent-agnostic.
3. Split when a task needs company: ⌘D terminal right (tests/logs), ⌥⌘D browser right (visual check).
4. Jump between tasks with ⌘1–⌘9 or fuzzy go-to ⌘P. Group related workspaces with ⌘⇧G.
5. Track state in the sidebar: mark done ⌘;, cycle status ⌘⇧;. Since v0.64.16, AI auto-naming titles workspaces from the agent conversation.

Workflow 2 — Never babysit: the notification loop

Three ways a process can notify:

# 1. the CLI (simplest)
cmux notify --title "Task Complete" --body "Your build finished"

# 2. OSC 777 (rxvt protocol) — plain escape, works from any language
printf '\e]777;notify;My Title;Message body here\a'

# 3. OSC 99 (kitty protocol) — supports subtitles and IDs
printf '\e]99;i=1;e=1;d=1;p=body:All tests passed\e\\'

Hook it to Claude Code by creating ~/.claude/hooks/cmux-notify.sh and registering it in ~/.claude/settings.json for the Stop (and optionally PostToolUse) events — every finished agent turn rings its own pane. Copilot CLI has equivalent lifecycle hooks (agentStop, errorOccurred, …).

Workflow 3 — Review & verify without leaving the terminal

• Diff viewer ⌃⌘⇧D — vim-style j/k scrolling, G/gg, / search; branch picker and inline review comments landed in v0.64.15–17.
• Browser split ⌥⌘D — open the dev server next to the agent; DevTools ⌥⌘I, JS console ⌥⌘C; “React Grab” ⌘⇧G to pick components.
• Global search ⌥⌘F across sessions; copy mode ⌘⇧M for keyboard text selection.

Workflow 4 — Claude Code Teams as native splits

cmux claude-teams              # launches Claude Code with agent teams enabled
cmux claude-teams --continue --model sonnet

Teammate agents appear as native cmux splits — with sidebar metadata and per-teammate notifications — instead of raw tmux panes. Similar wrappers exist for other agents: oh-my-opencode, oh-my-codex, oh-my-pi, oh-my-claudecode.

Sources: docs/notifications · docs/keyboard-shortcuts · docs/claude-code-teams · docs/changelog

7 · Keyboard shortcuts that matter

Curated high-value set. Full list (rebindable since v0.64.15, with context clauses): docs/keyboard-shortcuts.

Source: docs/keyboard-shortcuts

8 · Programmability: CLI, socket, skills, fleets

The socket protocol

One newline-terminated JSON request per call to /tmp/cmux.sock (override with CMUX_SOCKET_PATH):

{"id":"ws-list","method":"workspace.list","params":{}}
→ {"id":"ws-list","ok":true,"result":{"workspaces":[…]}}

The cmux CLI wraps the same methods. Useful flags: --json, --workspace ID, --surface ID, --socket PATH. Inside a pane, CMUX_WORKSPACE_ID and CMUX_SURFACE_ID are auto-set, so a script always knows where it lives.

Command map

The fleet pattern: agents driving agents

Because cmux terminals are addressable, a primary agent can stand up, prompt, observe, and tear down a whole fleet of other agents. Four verbs form the control loop (pattern popularized by disler/learning-cmux-with-agents, 31 prompts from single-workspace basics to multi-window fleets):

• Event-driven > polling: subscribe with cmux events instead of re-reading screens.
• Secrets: inject credentials with --env-file rather than typing them into panes; per-workspace env vars since v0.64.16.
• Reproducible layouts: declarative cmux.json defines project-specific commands and team bootstraps; save any layout as a template with ⌃⌘S.
• Visual identity: per-workspace colors/icons to tell fleet roles apart at a glance.

Official skills (teach your agent cmux)

Seven skills ship with cmux: Core (topology control), Workspace (current-workspace automation), Settings, Customization (actions, layouts, buttons, shortcuts), Diagnostics (CLI/socket health), Browser (webview automation), Markdown Viewer (live-reloading panels).

Sources: docs/api · docs/browser-automation · docs/skills · learning-cmux-with-agents

9 · cmux vs everything else

The key sorting question: which layer does the tool live at? Terminal (rendering + panes), multiplexer (session persistence), orchestrator (worktrees, task queues, review flows), or cloud agent (autonomous remote engineer). cmux is a terminal that borrows tricks from all layers while refusing to become an orchestrator.

When to pick what

Sources: cmux.com/compare (16 official comparisons) · Ry Walker research note · amux 2026 multiplexer survey

10 · Power tips & gotchas

Power tips

• Wrap long commands: a notify-after npm run build-style wrapper (docs show the pattern) auto-rings when anything slow finishes — not just agents.
• Notification hooks as filters: cmux.json hooks receive each notification as JSON on stdin and return modified effects — mute noisy panes, change sounds, filter history. Hooks trigger a trust prompt before first execution.
• Templates: build your ideal review layout (agent + tests + browser) once, save with ⌃⌘S, stamp it out per task.
• Agent hibernation (v0.64.11+) parks idle sessions to save resources; detachable SSH PTY daemon keeps remote sessions alive across disconnects.
• iOS app: check unread agent notifications and switch between multiple Macs from your phone (TestFlight beta since v0.64.14).
• Vault, TextBox, Task Manager, Dock, custom sidebars: newer subsystems worth exploring in the docs — vault, textbox (composer, ⌘⇧A), task-manager, dock.

Gotchas

• Not an orchestrator, on purpose. No git-worktree management, agent lifecycle, or task scheduling. If you expected the 2025 cmux, that's Manaflow now.
• Session restore ≠ process restore. Layout, directories, and scrollback survive relaunch; running processes (tmux, vim) do not.
• Performance trade-off: third-party review reports laggier scrolling / higher CPU than plain Ghostty, and a large open-issue count reflecting very fast release velocity (multiple releases per week). Pin expectations accordingly.
• Licensing: GPL-3.0-or-later — organizations that can't comply with copyleft need a commercial license from Manaflow.
• Socket security: default access is cmux child processes only (ancestry-verified). allowAll lets any local process control your terminal, type keystrokes, and read screens — enable only when you understand that.
• Old articles describe the old cmux. Anything mentioning Docker containers, VS Code instances, or Crown evaluation predates Feb 2026.

Sources: docs/changelog · docs/notifications · docs/session-restore · Ry Walker research note (third-party assessment)

11 · Self-test quiz

Reveal each answer, then score yourself honestly. Aim for 10/12 before calling yourself dangerous.

12 · Sources

Everything above traces to these, fetched 2026-07-09.

Official

• cmux.com — product site · /compare (16 tool comparisons)
• github.com/manaflow-ai/cmux — source, README, license
• Docs: getting-started · concepts · keyboard-shortcuts · api · notifications · browser-automation · skills · session-restore · ssh · workspace-groups · configuration · custom-commands · changelog
• Agent integrations: claude-code-teams · oh-my-opencode · oh-my-codex · oh-my-pi · oh-my-claudecode
• github.com/manaflow-ai/manaflow — the ex-cmux containerized orchestrator

Community & third-party

• disler/learning-cmux-with-agents — 31 fleet-orchestration prompts
• rywalker.com/research/cmux — independent assessment (strengths, limits, traction)
• Hacker News launches — Feb 19 2026 Show HN (terminal); Oct 30 2025 (0github diff viewer)
• ScriptByAI — the old orchestrator's parallel-agents + Crown workflow
• amux.io 2026 multiplexer survey · awesome-agent-orchestrators · awesome-cli-coding-agents — ecosystem context