97085be775
* Remove index-based CLI APIs and make commands workspace-relative Migrate 14 CLI commands from v1 text protocol to v2 JSON-RPC, making them workspace-relative via CMUX_WORKSPACE_ID env var fallback. Update 7 more commands to use normalize functions instead of legacy resolvers. Remove dead code (5 structs, 5 parsers, 3 functions). Add regression tests. Commands migrated v1→v2: send, send-key, send-panel, send-key-panel, new-split, new-pane, new-surface, close-surface, list-panes, list-pane-surfaces, list-panels, surface-health, focus-pane, focus-panel. Commands updated: move-workspace-to-window, list-workspaces, close-workspace, select-workspace, trigger-flash, resolveWorkspaceId, resolveSurfaceId. * Fix CMUX_SURFACE_ID env fallback when --workspace is overridden When --workspace is explicitly passed, don't fall back to CMUX_SURFACE_ID from the caller's environment. The caller's surface belongs to a different workspace, causing "surface not found" errors. Only use the env var fallback when the workspace is implicit (from CMUX_WORKSPACE_ID or server default). Affects: send, send-key, new-split, close-surface, trigger-flash, identify, notify, claude-hook. * Validate surface before close and respect -- option terminator in send P1: close-surface now validates the surface handle exists before sending surface.close, preventing silent fallback to focused surface when a stale or mistyped ref is provided. P2: parseOption now respects -- as an option terminator. send, send-key, send-panel, send-key-panel strip the -- marker from payload args. This prevents payload tokens like --workspace from being consumed as routing flags (e.g. `cmux send -- echo --workspace foo` sends all text correctly). * Fix test_send_workspace_relative: add to main() and send valid text The test was never called from main() and sent empty string which would raise immediately via _run_cli. Send a space character instead and add the test to the main() call list. * Respect --id-format in text output and resolve workspace refs across windows Text-mode list commands (list-workspaces, list-panes, list-panels, list-pane-surfaces, surface-health) now honor --id-format for plain output, not just --json. Added textHandle() helper that picks ref/id/both based on the selected format. resolveWorkspaceId now enumerates all windows when resolving a workspace ref, so notify/claude-hook work correctly in multi-window sessions where the target workspace may be in a non-active window. * Preserve escape-sequence semantics for send text The v1 server unescaped \n, \r, \t in send payloads before injecting into the terminal. The v2 surface.send_text handler sends text verbatim. Add CLI-side unescapeSendText() to restore the same behavior: \n and \r map to carriage return (Enter key), \t maps to tab. Applied to send and send-panel commands. * Reject malformed handles instead of passing through to server All four normalize functions (window, workspace, pane, surface) now throw a clear error for unrecognized handle formats instead of passing them through. Previously, a typo like `--panel foo` would forward `foo` to the server which would silently fall back to the focused surface. * Allow cross-workspace surface refs in close-surface and strip plural ID arrays Remove workspace-scoped pre-validation from close-surface so explicit surface refs/UUIDs from other workspaces work without requiring --workspace. The server resolves workspace from surface_id directly. Malformed handles are already caught by normalizeSurfaceHandle. Extend formatIDs to strip plural _ids/_refs array pairs (e.g. surface_ids/surface_refs in pane.list output) based on --id-format, matching the existing singular _id/_ref stripping behavior. * Honor explicit --window over CMUX_WORKSPACE_ID env fallback When --window is passed globally, skip the CMUX_WORKSPACE_ID env var fallback so commands operate on the targeted window's selected workspace instead of the caller's workspace from a different window. Affects all migrated commands that use workspaceFromArgsOrEnv or inline env fallback. |
||
|---|---|---|
| .claude/commands | ||
| .github/workflows | ||
| Assets.xcassets | ||
| CLI | ||
| cmuxTests | ||
| cmuxUITests | ||
| docs | ||
| ghostty@d641319cd9 | ||
| GhosttyTabs.xcodeproj | ||
| homebrew-cmux@1da02f8acb | ||
| node_modules | ||
| Resources | ||
| scripts | ||
| skills | ||
| Sources | ||
| tests | ||
| tests_v2 | ||
| vendor | ||
| web | ||
| .gitignore | ||
| .gitmodules | ||
| .vercelignore | ||
| AGENTS.md | ||
| bun.lock | ||
| CHANGELOG.md | ||
| CLAUDE.md | ||
| cmux-Bridging-Header.h | ||
| cmux.entitlements | ||
| CONTRIBUTING.md | ||
| ghostty.h | ||
| LICENSE | ||
| package.json | ||
| Package.resolved | ||
| Package.swift | ||
| PROJECTS.md | ||
| README.ar.md | ||
| README.bs.md | ||
| README.da.md | ||
| README.de.md | ||
| README.es.md | ||
| README.fr.md | ||
| README.it.md | ||
| README.ja.md | ||
| README.ko.md | ||
| README.md | ||
| README.no.md | ||
| README.pl.md | ||
| README.pt-BR.md | ||
| README.ru.md | ||
| README.th.md | ||
| README.tr.md | ||
| README.zh-CN.md | ||
| README.zh-TW.md | ||
| THIRD_PARTY_LICENSES.md | ||
| TODO.md | ||
cmux
A Ghostty-based macOS terminal with vertical tabs and notifications for AI coding agents
English | 简体中文 | 繁體中文 | 한국어 | Deutsch | Español | Français | Italiano | Dansk | 日本語 | Polski | Русский | Bosanski | العربية | Norsk | Português (Brasil) | ไทย | Türkçe
Features
Notification ringsPanes get a blue ring and tabs light up when AI agents need your attention |
|
Notification panelSee all pending notifications in one place, jump to the most recent unread |
|
In-app browserSplit a browser alongside your terminal with a scriptable API ported from agent-browser |
|
Vertical + horizontal tabsSidebar shows git branch, working directory, listening ports, and latest notification text. Split horizontally and vertically. |
|
- Scriptable — CLI and socket API to create workspaces, split panes, send keystrokes, and automate the browser
- Native macOS app — Built with Swift and AppKit, not Electron. Fast startup, low memory.
- Ghostty compatible — Reads your existing
~/.config/ghostty/configfor themes, fonts, and colors - GPU-accelerated — Powered by libghostty for smooth rendering
Install
DMG (recommended)
Open the .dmg and drag cmux to your Applications folder. cmux auto-updates via Sparkle, so you only need to download once.
Homebrew
brew tap manaflow-ai/cmux
brew install --cask cmux
To update later:
brew upgrade --cask cmux
On first launch, macOS may ask you to confirm opening an app from an identified developer. Click Open to proceed.
Why cmux?
I run a lot of Claude Code and Codex sessions in parallel. I was using Ghostty with a bunch of split panes, and relying on native macOS notifications to know when an agent needed me. But Claude Code's notification body is always just "Claude is waiting for your input" with no context, and with enough tabs open I couldn't even read the titles anymore.
I tried a few coding orchestrators but most of them were Electron/Tauri apps and the performance bugged me. I also just prefer the terminal since GUI orchestrators lock you into their workflow. So I built cmux as a native macOS app in Swift/AppKit. It uses libghostty for terminal rendering and reads your existing Ghostty config for themes, fonts, and colors.
The main additions are the sidebar and notification system. The sidebar has vertical tabs that show git branch, working directory, listening ports, and the latest notification text for each workspace. The notification system picks up terminal sequences (OSC 9/99/777) and has a CLI (cmux notify) you can wire into agent hooks for Claude Code, OpenCode, etc. When an agent is waiting, its pane gets a blue ring and the tab lights up in the sidebar, so I can tell which one needs me across splits and tabs. Cmd+Shift+U jumps to the most recent unread.
The in-app browser has a scriptable API ported from agent-browser. Agents can snapshot the accessibility tree, get element refs, click, fill forms, and evaluate JS. You can split a browser pane next to your terminal and have Claude Code interact with your dev server directly.
Everything is scriptable through the CLI and socket API — create workspaces/tabs, split panes, send keystrokes, open URLs in the browser.
Keyboard Shortcuts
Workspaces
| Shortcut | Action |
|---|---|
| ⌘ N | New workspace |
| ⌘ 1–8 | Jump to workspace 1–8 |
| ⌘ 9 | Jump to last workspace |
| ⌃ ⌘ ] | Next workspace |
| ⌃ ⌘ [ | Previous workspace |
| ⌘ ⇧ W | Close workspace |
| ⌘ B | Toggle sidebar |
Surfaces
| Shortcut | Action |
|---|---|
| ⌘ T | New surface |
| ⌘ ⇧ ] | Next surface |
| ⌘ ⇧ [ | Previous surface |
| ⌃ Tab | Next surface |
| ⌃ ⇧ Tab | Previous surface |
| ⌃ 1–8 | Jump to surface 1–8 |
| ⌃ 9 | Jump to last surface |
| ⌘ W | Close surface |
Split Panes
| Shortcut | Action |
|---|---|
| ⌘ D | Split right |
| ⌘ ⇧ D | Split down |
| ⌥ ⌘ ← → ↑ ↓ | Focus pane directionally |
| ⌘ ⇧ H | Flash focused panel |
Browser
| Shortcut | Action |
|---|---|
| ⌘ ⇧ L | Open browser in split |
| ⌘ L | Focus address bar |
| ⌘ [ | Back |
| ⌘ ] | Forward |
| ⌘ R | Reload page |
| ⌥ ⌘ I | Open Developer Tools |
Notifications
| Shortcut | Action |
|---|---|
| ⌘ I | Show notifications panel |
| ⌘ ⇧ U | Jump to latest unread |
Find
| Shortcut | Action |
|---|---|
| ⌘ F | Find |
| ⌘ G / ⌘ ⇧ G | Find next / previous |
| ⌘ ⇧ F | Hide find bar |
| ⌘ E | Use selection for find |
Terminal
| Shortcut | Action |
|---|---|
| ⌘ K | Clear scrollback |
| ⌘ C | Copy (with selection) |
| ⌘ V | Paste |
| ⌘ + / ⌘ - | Increase / decrease font size |
| ⌘ 0 | Reset font size |
Window
| Shortcut | Action |
|---|---|
| ⌘ ⇧ N | New window |
| ⌘ , | Settings |
| ⌘ ⇧ , | Reload configuration |
| ⌘ Q | Quit |
License
This project is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later).
See LICENSE for the full text.