Repository: manaflow-ai/cmux

Stars: 14478

CLAUDE.md

cmux agent notes

Initial setup

Run the setup script to initialize submodules and build GhosttyKit:

bash

./scripts/setup.sh

Local dev

After making code changes, always run the reload script with a tag to build the Debug app:

bash

./scripts/reload.sh --tag fix-zsh-autosuggestions

By default, reload.sh builds but does not launch the app. The script prints the .app path so the user can cmd-click to open it. After a successful build, it always terminates any running app with the same tag (so cmd-clicking launches the freshly-built binary instead of foregrounding the stale instance). Pass --launch to open the app automatically after the build:

bash

./scripts/reload.sh --tag fix-zsh-autosuggestions --launch

reload.sh prints an App path: line with the absolute path to the built .app. Use that path to build a cmd-clickable file:// URL. Steps:

1. Grab the path from the App path: line in reload.sh output.
2. Prepend file:// and URL-encode spaces as %20. Do not hardcode any part of the path.
3. Format it as a markdown link using the template for your agent type.

Example. If reload.sh output contains:

text

App path:
  /Users/someone/Library/Developer/Xcode/DerivedData/cmux-my-tag/Build/Products/Debug/cmux DEV my-tag.app

Claude Code outputs:

markdown

=======================================================
cmux DEV my-tag.app
=======================================================

Codex outputs:

text

=======================================================
my-tag: file:///Users/someone/Library/Developer/Xcode/DerivedData/cmux-my-tag/Build/Products/Debug/cmux%20DEV%20my-tag.app
=======================================================

Never use /tmp/cmux-<tag>/... app links in chat output.

After making code changes, always use reload.sh --tag to build. Never run bare xcodebuild or open an untagged cmux DEV.app. Untagged builds share the default debug socket and bundle ID with other agents, causing conflicts and stealing focus.

bash

./scripts/reload.sh --tag <your-branch-slug>

If you only need to verify the build compiles (no launch), use a tagged derivedDataPath:

bash

xcodebuild -project GhosttyTabs.xcodeproj -scheme cmux -configuration Debug -destination 'platform=macOS' -derivedDataPath /tmp/cmux-<your-tag> build

When rebuilding GhosttyKit.xcframework, always use Release optimizations:

bash

cd ghostty && zig build -Demit-xcframework=true -Dxcframework-target=universal -Doptimize=ReleaseFast

When rebuilding cmuxd for release/bundling, always use ReleaseFast:

bash

cd cmuxd && zig build -Doptimize=ReleaseFast

reload = build the Debug app (tag required) and terminate any running app with the same tag. Pass --launch to also open the freshly-built app:

bash

./scripts/reload.sh --tag <tag>
./scripts/reload.sh --tag <tag> --launch

reloadp = kill and launch the Release app:

bash

./scripts/reloadp.sh

reloads = kill and launch the Release app as "cmux STAGING" (isolated from production cmux):

bash

./scripts/reloads.sh

reload2 = reload both Debug and Release (tag required for Debug reload):

bash

./scripts/reload2.sh --tag <tag>

For parallel/isolated builds (e.g., testing a feature alongside the main app), use --tag with a short descriptive name:

bash

./scripts/reload.sh --tag fix-blur-effect

This creates an isolated app with its own name, bundle ID, socket, and derived data path so it runs side-by-side with the main app. Important: use a non-/tmp derived data path if you need xcframework resolution (the script handles this automatically).

Before launching a new tagged run, clean up any older tags you started in this session (quit old tagged app + remove its /tmp socket/derived data).

Debug event log

All debug events (keys, mouse, focus, splits, tabs) go to a unified log in DEBUG builds:

bash

tail -f "$(cat /tmp/cmux-last-debug-log-path 2>/dev/null || echo /tmp/cmux-debug.log)"

- Untagged Debug app: /tmp/cmux-debug.log
- Tagged Debug app (./scripts/reload.sh --tag <tag>): /tmp/cmux-debug-<tag>.log
- reload.sh writes the current path to /tmp/cmux-last-debug-log-path
- reload.sh writes the selected dev CLI path to /tmp/cmux-last-cli-path
- reload.sh updates /tmp/cmux-cli and $HOME/.local/bin/cmux-dev to that CLI

- Implementation: vendor/bonsplit/Sources/Bonsplit/Public/DebugEventLog.swift
- Free function dlog("message") — logs with timestamp and appends to file in real time
- Entire file is #if DEBUG; all call sites must be wrapped in #if DEBUG / #endif
- 500-entry ring buffer; DebugEventLog.shared.dump() writes full buffer to file
- Key events logged in AppDelegate.swift (monitor, performKeyEquivalent)
- Mouse/UI events logged inline in views (ContentView, BrowserPanelView, etc.)
- Focus events: focus.panel, focus.bonsplit, focus.firstResponder, focus.moveFocus
- Bonsplit events: tab.select, tab.close, tab.dragStart, tab.drop, pane.focus, pane.drop, divider.dragStart

Regression test commit policy

When adding a regression test for a bug fix, use a two-commit structure so CI proves the test catches the bug:

1. Commit 1: Add the failing test only (no fix). CI should go red.
2. Commit 2: Add the fix. CI should go green.

This makes it visible in the GitHub PR UI (Commits tab, check statuses) that the test genuinely fails without the fix.

The app has a Debug menu in the macOS menu bar (only in DEBUG builds). Use it for visual iteration:

- Debug > Debug Windows contains panels for tuning layout, colors, and behavior. Entries are alphabetical with no dividers.
- To add a debug toggle or visual option: create an NSWindowController subclass with a shared singleton, add it to the "Debug Windows" menu in Sources/cmuxApp.swift, and add a SwiftUI view with @AppStorage bindings for live changes.
- When the user says "debug menu" or "debug window", they mean this menu, not defaults write.

Pitfalls

- Custom UTTypes for drag-and-drop must be declared in Resources/Info.plist under UTExportedTypeDeclarations (e.g. com.splittabbar.tabtransfer, com.cmux.sidebar-tab-reorder).
- Do not add an app-level display link or manual ghostty_surface_draw loop; rely on Ghostty wakeups/renderer to avoid typing lag.
- Typing-latency-sensitive paths (read carefully before touching these areas):
- WindowTerminalHostView.hitTest() in TerminalWindowPortal.swift: called on every event including keyboard. All divider/sidebar/drag routing is gated to pointer events only. Do not add work outside the isPointerEvent guard.
- TabItemView in ContentView.swift: uses Equatable conformance + .equatable() to skip body re-evaluation during typing. Do not add @EnvironmentObject, @ObservedObject (besides tab), or @Binding properties without updating the == function. Do not remove .equatable() from the ForEach call site. Do not read tabManager or notificationStore in the body; use the precomputed let parameters instead.
- TerminalSurface.forceRefresh() in GhosttyTerminalView.swift: called on every keystroke. Do not add allocations, file I/O, or formatting here.
- Terminal find layering contract: SurfaceSearchOverlay must be mounted from GhosttySurfaceScrollView in Sources/GhosttyTerminalView.swift (AppKit portal layer), not from SwiftUI panel containers such as Sources/Panels/TerminalPanelView.swift. Portal-hosted terminal views can sit above SwiftUI during split/workspace churn.
- Submodule safety: When modifying a submodule (ghostty, vendor/bonsplit, etc.), always push the submodule commit to its remote main branch BEFORE committing the updated pointer in the parent repo. Never commit on a detached HEAD or temporary branch — the commit will be orphaned and lost. Verify with: cd <submodule> && git merge-base --is-ancestor HEAD origin/main.
- All user-facing strings must be localized. Use String(localized: "key.name", defaultValue: "English text") for every string shown in the UI (labels, buttons, menus, dialogs, tooltips, error messages). Keys go in Resources/Localizable.xcstrings with translations for all supported languages (currently English and Japanese). Never use bare string literals in SwiftUI Text(), Button(), alert titles, etc.
- Shortcut policy: Every new cmux-owned keyboard shortcut must be added to KeyboardShortcutSettings, visible/editable in Settings, supported in ~/.config/cmux/settings.json, and documented in the keyboard shortcut and configuration docs.

Test quality policy

- Do not add tests that only verify source code text, method signatures, AST fragments, or grep-style patterns.
- Do not add tests that read checked-in metadata or project files such as Resources/Info.plist, project.pbxproj, .xcconfig, or source files only to assert that a key, string, plist entry, or snippet exists.
- Tests must verify observable runtime behavior through executable paths (unit/integration/e2e/CLI), not implementation shape.
- For metadata changes, prefer verifying the built app bundle or the runtime behavior that depends on that metadata, not the checked-in source file.
- If a behavior cannot be exercised end-to-end yet, add a small runtime seam or harness first, then test through that seam.
- If no meaningful behavioral or artifact-level test is practical, skip the fake regression test and state that explicitly.

Socket command threading policy

- Do not use DispatchQueue.main.sync for high-frequency socket telemetry commands (report_*, ports_kick, status/progress/log metadata updates).
- For telemetry hot paths:
- Parse and validate arguments off-main.
- Dedupe/coalesce off-main first.
- Schedule minimal UI/model mutation with DispatchQueue.main.async only when needed.
- Commands that directly manipulate AppKit/Ghostty UI state (focus/select/open/close/send key/input, list/current queries requiring exact synchronous snapshot) are allowed to run on main actor.
- If adding a new socket command, default to off-main handling; require an explicit reason in code comments when main-thread execution is necessary.

Socket focus policy

- Socket/CLI commands must not steal macOS app focus (no app activation/window raising side effects).
- Only explicit focus-intent commands may mutate in-app focus/selection (window.focus, workspace.select/next/previous/last, surface.focus, pane.focus/last, browser focus commands, and v1 focus equivalents).
- All non-focus commands should preserve current user focus context while still applying data/model changes.

Testing policy

Never run tests locally. All tests (E2E, UI, python socket tests) run via GitHub Actions or on the VM.

- E2E / UI tests: trigger via gh workflow run test-e2e.yml (see cmuxterm-hq CLAUDE.md for details)
- Unit tests: xcodebuild -scheme cmux-unit is safe (no app launch), but prefer CI
- Python socket tests (tests_v2/): these connect to a running cmux instance's socket. Never launch an untagged cmux DEV.app to run them. If you must test locally, use a tagged build's socket (/tmp/cmux-debug-<tag>.sock) with CMUX_SOCKET=/tmp/cmux-debug-<tag>.sock
- Never open an untagged cmux DEV.app from DerivedData. It conflicts with the user's running debug instance.

Ghostty submodule workflow

Ghostty changes must be committed in the ghostty submodule and pushed to the manaflow-ai/ghostty fork.
Keep docs/ghostty-fork.md up to date with any fork changes and conflict notes.

bash

cd ghostty
git remote -v  # origin = upstream, manaflow = fork
git checkout -b <branch>
git add <files>
git commit -m "..."
git push manaflow <branch>

To keep the fork up to date with upstream:

bash

cd ghostty
git fetch origin
git checkout main
git merge origin/main
git push manaflow main

Then update the parent repo with the new submodule SHA:

bash

cd ..
git add ghostty
git commit -m "Update ghostty submodule"

Release

Use the /release command to prepare a new release. This will:
1. Determine the new version (bumps minor by default)
2. Gather commits since the last tag and update the changelog
3. Update CHANGELOG.md (the docs changelog page at web/app/docs/changelog/page.tsx reads from it)
4. Run ./scripts/bump-version.sh to update both versions
5. Commit, run ./scripts/release-pretag-guard.sh, tag, and push

Version bumping:

bash

./scripts/bump-version.sh          # bump minor (0.15.0 → 0.16.0)
./scripts/bump-version.sh patch    # bump patch (0.15.0 → 0.15.1)
./scripts/bump-version.sh major    # bump major (0.15.0 → 1.0.0)
./scripts/bump-version.sh 1.0.0    # set specific version

This updates both MARKETING_VERSION and CURRENT_PROJECT_VERSION (build number). The build number is auto-incremented and is required for Sparkle auto-update to work.

Before creating a release tag, run:

bash

./scripts/release-pretag-guard.sh

If it fails, run ./scripts/bump-version.sh, commit the build-number bump, then retry tagging.

Manual release steps (if not using the command):

bash

./scripts/release-pretag-guard.sh
git tag vX.Y.Z
git push origin vX.Y.Z
gh run watch --repo manaflow-ai/cmux

Notes:
- Requires GitHub secrets: APPLE_CERTIFICATE_BASE64, APPLE_CERTIFICATE_PASSWORD,
APPLE_SIGNING_IDENTITY, APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, APPLE_TEAM_ID.
- The release asset is cmux-macos.dmg attached to the tag.
- README download button points to releases/latest/download/cmux-macos.dmg.
- Versioning: bump the minor version for updates unless explicitly asked otherwise.
- Changelog: update CHANGELOG.md; docs changelog is rendered from it.

README.md

<h1 align="center">cmux</h1>
<p align="center">A Ghostty-based macOS terminal with vertical tabs and notifications for AI coding agents</p>

<p align="center">
<a href="https://www.youtube.com/watch?v=i-WxO5YUTOs">▶ Demo video</a> · <a href="https://cmux.com/blog/zen-of-cmux">The Zen of cmux</a>
</p>

Features

<table>
<tr>
<td width="40%" valign="middle">
<h3>Notification rings</h3>
Panes get a blue ring and tabs light up when coding agents need your attention
</td>
<td width="60%">
<img src="./docs/assets/notification-rings.png" alt="Notification rings" width="100%" />
</td>
</tr>
<tr>
<td width="40%" valign="middle">
<h3>Notification panel</h3>
See all pending notifications in one place, jump to the most recent unread
</td>
<td width="60%">
<img src="./docs/assets/sidebar-notification-badge.png" alt="Sidebar notification badge" width="100%" />
</td>
</tr>
<tr>
<td width="40%" valign="middle">
<h3>In-app browser</h3>
Split a browser alongside your terminal with a scriptable API ported from <a href="https://github.com/vercel-labs/agent-browser">agent-browser</a>
</td>
<td width="60%">
<img src="./docs/assets/built-in-browser.png" alt="Built-in browser" width="100%" />
</td>
</tr>
<tr>
<td width="40%" valign="middle">
<h3>Vertical + horizontal tabs</h3>
Sidebar shows git branch, linked PR status/number, working directory, listening ports, and latest notification text. Split horizontally and vertically.
</td>
<td width="60%">
<img src="./docs/assets/vertical-horizontal-tabs-and-splits.png" alt="Vertical tabs and split panes" width="100%" />
</td>
</tr>
<tr>
<td width="40%" valign="middle">
<h3>SSH</h3>
<code>cmux ssh user@remote</code> creates a workspace for a remote machine. Browser panes route through the remote network so localhost just works. Drag an image into a remote session to upload via scp.
</td>
<td width="60%">
<img src="./docs/assets/ssh.png" alt="cmux SSH" width="100%" />
</td>
</tr>
<tr>
<td width="40%" valign="middle">
<h3>Claude Code Teams</h3>
<code>cmux claude-teams</code> runs Claude Code's teammate mode with one command. Teammates spawn as native splits with sidebar metadata and notifications. No tmux required.
</td>
<td width="60%">
<img src="./docs/assets/claude-code-teams.png" alt="Claude Code Teams" width="100%" />
</td>
</tr>
</table>

- Browser import — Import cookies, history, and sessions from Chrome, Firefox, Arc, and 20+ browsers so browser panes start authenticated
- Custom commands — Define project-specific actions in cmux.json that launch from the command palette
- 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/config for 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

bash

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

To update later:

bash

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, linked PR status/number, 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.

The Zen of cmux

cmux is not prescriptive about how developers hold their tools. It's a terminal and browser with a CLI, and the rest is up to you.

cmux is a primitive, not a solution. It gives you a terminal, a browser, notifications, workspaces, splits, tabs, and a CLI to control all of it. cmux doesn't force you into an opinionated way to use coding agents. What you build with the primitives is yours.

The best developers have always built their own tools. Nobody has figured out the best way to work with agents yet, and the teams building closed products definitely haven't either. The developers closest to their own codebases will figure it out first.

Give a million developers composable primitives and they'll collectively find the most efficient workflows faster than any product team could design top-down.

Documentation

For more info on how to configure cmux, head over to our docs.

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 |
| ⌘ ⇧ R | Rename 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

Browser developer-tool shortcuts follow Safari defaults and are customizable in Settings → Keyboard Shortcuts.

| Shortcut | Action |
|----------|--------|
| ⌘ ⇧ L | Open browser in split |
| ⌘ L | Focus address bar |
| ⌘ [ | Back |
| ⌘ ] | Forward |
| ⌘ R | Reload page |
| ⌥ ⌘ I | Toggle Developer Tools (Safari default) |
| ⌥ ⌘ C | Show JavaScript Console (Safari default) |

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 |

Nightly Builds

Download cmux NIGHTLY

cmux NIGHTLY is a separate app with its own bundle ID, so it runs alongside the stable version. Built automatically from the latest main commit and auto-updates via its own Sparkle feed.

Report nightly bugs on GitHub Issues or in #nightly-bugs on Discord.

Session restore (current behavior)

On relaunch, cmux currently restores app layout and metadata only:
- Window/workspace/pane layout
- Working directories
- Terminal scrollback (best effort)
- Browser URL and navigation history

cmux does not restore live process state inside terminal apps. For example, active Claude Code/tmux/vim sessions are not resumed after restart yet.

Star History

Contributing

Ways to get involved:

- Follow us on X for updates @manaflowai, @lawrencecchen, and @austinywang
- Join the conversation on Discord
- Create and participate in GitHub issues and discussions
- Let us know what you're building with cmux

Community

- Discord
- GitHub
- X / Twitter
- YouTube
- LinkedIn
- Reddit

Founder's Edition

cmux is free, open source, and always will be. If you'd like to support development and get early access to what's coming next:

Get Founder's Edition

- Prioritized feature requests/bug fixes
- Early access: cmux AI that gives you context on every workspace, tab and panel
- Early access: iOS app with terminals synced between desktop and phone
- Early access: Cloud VMs
- Early access: Voice mode
- My personal iMessage/WhatsApp

License

cmux is open source under GPL-3.0-or-later.

If your organization cannot comply with GPL, a commercial license is available. Contact [email protected] for details.

Repository: manaflow-ai/cmux

Stars: 14478

CLAUDE.md Copy Chapter

cmux agent notes

Initial setup Copy Chapter

Local dev Copy Chapter

Debug event log Copy Chapter

Regression test commit policy Copy Chapter

Debug menu Copy Chapter

Pitfalls Copy Chapter

Test quality policy Copy Chapter

Socket command threading policy Copy Chapter

Socket focus policy Copy Chapter

Testing policy Copy Chapter

Ghostty submodule workflow Copy Chapter

Release Copy Chapter

README.md Copy Chapter

Features Copy Chapter

Install Copy Chapter

DMG (recommended) Copy Section

Homebrew Copy Section

Why cmux? Copy Chapter

The Zen of cmux Copy Chapter

Documentation Copy Chapter

Keyboard Shortcuts Copy Chapter

Workspaces Copy Section

Surfaces Copy Section

Split Panes Copy Section

Browser Copy Section

Notifications Copy Section

Find Copy Section

Terminal Copy Section

Window Copy Section

Nightly Builds Copy Chapter

Session restore (current behavior) Copy Chapter

Star History Copy Chapter

Contributing Copy Chapter

Community Copy Chapter

Founder's Edition Copy Chapter

License Copy Chapter

CLAUDE.md

Initial setup

Local dev

Debug event log

Regression test commit policy

Debug menu

Pitfalls

Test quality policy

Socket command threading policy

Socket focus policy

Testing policy

Ghostty submodule workflow

Release

README.md

Features

Install

DMG (recommended)

Homebrew

Why cmux?

The Zen of cmux

Documentation

Keyboard Shortcuts

Workspaces

Surfaces

Split Panes

Browser

Notifications

Find

Terminal

Window

Nightly Builds

Session restore (current behavior)

Star History

Contributing

Community

Founder's Edition

License