484b66c8ac
* Fix terminal keys (arrows, Ctrl+N/P) swallowed after opening browser After a browser panel is shown, SwiftUI's internal focus system activates and its _NSHostingView starts consuming arrow keys and other non-Command key events via performKeyEquivalent, preventing them from reaching the terminal's keyDown handler. Fix: In the NSWindow performKeyEquivalent swizzle, when GhosttyNSView is the first responder and the event has no Command modifier, route directly to the terminal's performKeyEquivalent — bypassing SwiftUI's view hierarchy walk entirely. Also clear stale browserAddressBarFocusedPanelId when a terminal surface has focus, preventing Cmd+N from being eaten by omnibar selection logic after focus transitions away from a browser. Adds DEBUG-only keyboard event ring buffer (KeyDebugLog) that dumps to /tmp/cmux-key-debug.log for diagnosing future key routing issues. * Fix split focus and Cmd+Shift+N swallowed after opening browser Split focus: capture the source terminal's hostedView before bonsplit mutates focusedPaneId, so focusPanel moves focus FROM the old pane instead of from the new pane to itself. Also retry ensureFocus when the new terminal's view has no window yet (matching the existing retry pattern for isVisibleInUI). Cmd+Shift+N: after WKWebView has been in the responder chain, SwiftUI's internal focus system can intercept Command-key events in the content view hierarchy (returning true) without firing the CommandGroup action closure. Fix by dispatching Command-key events directly to NSApp.mainMenu when the terminal is first responder, bypassing the broken SwiftUI path. Also add Cmd+Shift+N to handleCustomShortcut so it's customizable and doesn't depend on SwiftUI menu dispatch at all. * Unified debug event log: merge key/mouse/focus into /tmp/cmux-debug.log - Delete KeyDebugLog, MouseDebugLog, klog(), mlog() from AppDelegate - Replace all klog/mlog calls with dlog() (provided by bonsplit) - Remove debugLogCallback wiring from Workspace - Add focus change logging: focus.panel, focus.firstResponder, split.created, focus.moveFocus - Add import Bonsplit where needed for dlog access - Fix stale drag state on cancelled tab drags (bonsplit submodule) * Fix split focus stolen by re-entrant becomeFirstResponder during reparenting During programmatic splits (Cmd+D / Cmd+Shift+D), SwiftUI reparents the old terminal view, which fires becomeFirstResponder → onFocus → focusPanel for the OLD panel, stealing focus from the newly created pane. Add programmaticFocusTargetPanelId guard to suppress re-entrant focusPanel calls for non-target panels during split creation. Also document the unified debug event log in CLAUDE.md. * Clear stale title/favicon when browser navigation fails When a page fails to load (e.g. connection refused), the tab was still showing the previous page's title and favicon. Now didFailProvisionalNavigation resets pageTitle to the failed URL and clears faviconPNGData. * Fix Cmd+N swallowed by browser omnibar and improve split focus suppression - Only Ctrl+N/P trigger omnibar navigation, not Cmd+N/P (Cmd+N should always create new workspace regardless of address bar focus) - Move split focus suppression from workspace-level guard to source: suppress becomeFirstResponder side-effects (onFocus + ghostty_surface_set_focus) directly on the old GhosttyNSView during reparenting, preventing both model-level and libghostty-level focus divergence - Remove programmaticFocusTargetPanelId from Workspace.focusPanel * Fix omnibar hang, WebView white flash, drag-over-browser, and idle CPU spin - Omnibar: first click selects all without entering NSTextView tracking loop; subsequent clicks have 3s synthetic mouseUp safety net to prevent hang - WebView: set underPageBackgroundColor to match window so new browsers don't flash white before content loads - Drag/drop: register custom UTType (com.splittabbar.tabtransfer) in Info.plist so WKWebView doesn't intercept tab drags; override registerForDraggedTypes on CmuxWebView as belt-and-suspenders - CPU: fix infinite makeFirstResponder loop in controlTextDidEndEditing by checking both the text field and its field editor (the actual first responder) |
||
|---|---|---|
| .claude/commands | ||
| .github/workflows | ||
| Assets.xcassets | ||
| CLI | ||
| docs | ||
| docs-site | ||
| ghostty@5a987a1485 | ||
| GhosttyTabs.xcodeproj | ||
| GhosttyTabsTests | ||
| GhosttyTabsUITests | ||
| homebrew-cmux@19af91f6d4 | ||
| 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
- Vertical tabs — Sidebar shows git branch, working directory, listening ports, and latest notification text
- Notification rings — Panes get a blue ring and tabs light up when AI agents (Claude Code, OpenCode) need your attention
- Notification panel — See all pending notifications in one place, jump to the most recent unread
- Split panes — Horizontal and vertical splits
- In-app browser — Split a browser alongside your terminal with a scriptable API ported from agent-browser
- 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.