Skip to main content
This guide will get you from installation to your first meaningful workflow: creating workspaces, setting up notifications, and using the in-app browser.

​
Prerequisites

  • cmux installed (see Installation)
  • Basic familiarity with terminal commands

​
Launch cmux

Open cmux from your Applications folder or via Spotlight (Cmd+Space, type “cmux”). On first launch, you’ll see a single workspace with a terminal. The sidebar on the left shows your workspace tabs.

​
Create a workspace

Workspaces are the top-level organizing unit in cmux. Each workspace can contain multiple split panes and surfaces (terminals and browsers).
1

Create a new workspace

Press Cmd+N or use the CLI:
cmux new-workspace
You can also create a workspace in a specific directory:
cmux new-workspace --cwd ~/projects/myapp
2

Navigate between workspaces

Use keyboard shortcuts to switch workspaces:
ShortcutAction
Cmd+1–8Jump to workspace 1–8
Cmd+9Jump to last workspace
Ctrl+Cmd+]Next workspace
Ctrl+Cmd+[Previous workspace
3

Rename a workspace

Press Cmd+Shift+R or use the CLI:
cmux rename-workspace "My Project"

​
Split panes

Split your workspace horizontally or vertically to work with multiple terminals side-by-side.
1

Split right

Press Cmd+D to create a vertical split.
2

Split down

Press Cmd+Shift+D to create a horizontal split.
3

Navigate between panes

Use Opt+Cmd+Arrow to focus panes directionally.
4

Flash focused pane

Press Cmd+Shift+H to briefly highlight which pane has focus.
You can also split panes via CLI: 
cmux new-split right
cmux new-split down

​
Set up notifications

Notifications are cmux’s killer feature for working with AI coding agents. When an agent needs your attention, its pane gets a blue ring and the tab lights up.
1

Send a test notification

cmux notify --title "Build Complete" --subtitle "myapp" --body "Tests passed"
You’ll see:
  • A blue ring around the current pane
  • The workspace tab glows in the sidebar
  • The notification appears in the notification panel
2

Open the notification panel

Press Cmd+I to see all notifications.
3

Jump to latest unread

Press Cmd+Shift+U to jump to the most recent unread notification.
4

Clear notifications

cmux clear-notifications

​
Terminal notification sequences

cmux also picks up standard terminal notification sequences (OSC 9/99/777): 
# OSC 777
echo -e "\033]777;notify;Build Complete;Tests passed\033\\"

# OSC 9
echo -e "\033]9;Build Complete\033\\"

# OSC 99
echo -e "\033]99;i=1:p=body;Build Complete\033\\"

​
Use the in-app browser

The in-app browser lets you view and automate web pages alongside your terminal.
1

Open browser in split

Press Cmd+Shift+L or use the CLI:
cmux browser open http://localhost:3000
2

Navigate to a URL

Press Cmd+L to focus the address bar, type a URL, and press Enter.Or via CLI:
cmux browser navigate http://example.com
3

Browser shortcuts

ShortcutAction
Cmd+LFocus address bar
Cmd+[Back
Cmd+]Forward
Cmd+RReload page
Opt+Cmd+IToggle Developer Tools
Opt+Cmd+CShow JavaScript Console

​
Scriptable browser API

The browser has a scriptable API ported from agent-browser for automation: 
# Get current URL
cmux browser get-url

# Navigate back/forward
cmux browser back
cmux browser forward

# Reload page
cmux browser reload
For advanced automation (accessibility tree snapshots, element interactions), see the Browser CLI reference.

​
Integrate with AI coding agents

cmux is designed to work seamlessly with AI coding tools. Here’s how to integrate with popular agents:

​
Claude Code

cmux has built-in Claude Code integration. To enable it:
1

Set up the hook

cmux can automatically notify you when Claude Code is waiting. The integration is enabled by default in recent versions.When Claude Code pauses for input, you’ll see a notification in the workspace where it’s running.
2

Resume from notifications

Press Cmd+Shift+U to jump to the latest Claude Code prompt.

​
OpenCode

For OpenCode or other agents, use the cmux notify command in your shell prompts or agent hooks: 
# In your agent's output handler
cmux notify --title "OpenCode" --subtitle "Waiting for input" --body "$PROMPT_TEXT"

​
Custom integrations

You can wire cmux notify into any tool that supports custom commands or hooks: 
# Example: notify when a long build finishes
make build && cmux notify --title "Build" --body "Build succeeded" || cmux notify --title "Build" --body "Build failed"

​
Keyboard shortcuts reference

Here are the essential shortcuts to get started:

​
Workspaces

ShortcutAction
Cmd+NNew workspace
Cmd+1–8Jump to workspace 1–8
Cmd+9Jump to last workspace
Ctrl+Cmd+]Next workspace
Ctrl+Cmd+[Previous workspace
Cmd+Shift+WClose workspace
Cmd+Shift+RRename workspace
Cmd+BToggle sidebar

​
Split panes

ShortcutAction
Cmd+DSplit right
Cmd+Shift+DSplit down
Opt+Cmd+ArrowFocus pane directionally
Cmd+Shift+HFlash focused panel

​
Notifications

ShortcutAction
Cmd+IShow notifications panel
Cmd+Shift+UJump to latest unread

​
Browser

ShortcutAction
Cmd+Shift+LOpen browser in split
Cmd+LFocus address bar
Cmd+[Back
Cmd+]Forward
Cmd+RReload page
For a complete list, see Keyboard Shortcuts.

​
Next steps

Workspaces & Tabs

Learn advanced workspace management

Notifications

Master the notification system

CLI Reference

Explore all CLI commands

Browser Automation

Automate the in-app browser