Workspaces
Each workspace is an independent environment that tracks:- Working directory
- Git branch and dirty state
- Listening ports
- Process title
- Custom color and icon
- Status metadata and logs
- Progress indicators
Workspaces are the equivalent of “windows” in traditional terminals but appear as vertical tabs in the sidebar instead of separate OS windows.
Creating workspaces
Create a new workspace:- Press ⌘ N
- Use the CLI:
cmux new-workspace - Click the ”+” button in the sidebar
Workspace metadata
The sidebar displays rich metadata for each workspace:- Git branch: Automatically detected from the working directory
- Dirty indicator: Shows when you have uncommitted changes
- Pull request: Linked PR number and status (open/merged/closed)
- Working directory: Current directory path
- Listening ports: Ports bound by processes in this workspace
- Latest notification: Most recent notification text from agents
Workspace metadata updates automatically as you work. Git status, ports, and directory changes are detected in real-time.
Custom titles and colors
Personalize workspaces with custom titles and colors:Workspace colors are set through the in-app settings, not via CLI.
- ⌘ ⇧ R to rename the current workspace
Pinned workspaces
Pin important workspaces to keep them at the top of the sidebar using the workspace context menu in the sidebar. Pinned workspaces stay in position even when new notifications arrive in other workspaces.Surfaces (tabs within a workspace)
Each workspace contains one or more surfaces. A surface is either a terminal or browser pane.Creating surfaces
- Press ⌘ T to create a new terminal surface
- Press ⌘ ⇧ L to create a new browser surface
Navigating surfaces
| Shortcut | Action |
|---|---|
| ⌘ ⇧ ] | 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 |
Workspace navigation
Switching workspaces
| Shortcut | Action |
|---|---|
| ⌘ 1–8 | Jump to workspace 1–8 |
| ⌘ 9 | Jump to last workspace |
| ⌃ ⌘ ] | Next workspace |
| ⌃ ⌘ [ | Previous workspace |
Closing workspaces
Close a workspace:- Press ⌘ ⇧ W
- Use the CLI:
cmux close-workspace --workspace <id> - Click the close button (×) on the workspace tab
Session restore
cmux automatically saves workspace state on quit and restores it on relaunch: Restored state:- Workspace layout and split pane structure
- Working directories
- Terminal scrollback (best effort, up to 5000 lines)
- Browser URLs and navigation history
- Custom titles, colors, and pinned state
- Metadata (git branch, ports, etc.)
- Live process state (tmux/vim sessions don’t resume)
- Active SSH connections
- Running builds or long-running commands
Terminal processes restart in the same working directory but don’t resume mid-execution. Use tmux or screen if you need persistent sessions across app restarts.
Sidebar
The vertical sidebar displays all workspaces and can be toggled with ⌘ B. Sidebar features:- Drag tabs to reorder workspaces
- Context menu on each tab for quick actions
- Visual indicators for notifications, git state, and activity
- Auto-reorder workspaces on notification (optional)
Working directory tracking
cmux automatically detects directory changes in terminal sessions and updates:- The workspace’s current directory
- Git branch detection in the new directory
- Relative path display in the sidebar
Command palette
Access the command palette with ⌘ ⇧ P to quickly:- Switch between workspaces across all windows
- Access update actions
- Execute common workspace operations