Quickstart

Get up and running with cmux in 5 minutes

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:

   Shortcut	Action
   Cmd+1–8	Jump to workspace 1–8
   Cmd+9	Jump 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

   Shortcut	Action
   Cmd+L	Focus address bar
   Cmd+[	Back
   Cmd+]	Forward
   Cmd+R	Reload page
   Opt+Cmd+I	Toggle Developer Tools
   Opt+Cmd+C	Show 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

Shortcut	Action
Cmd+N	New workspace
Cmd+1–8	Jump to workspace 1–8
Cmd+9	Jump to last workspace
Ctrl+Cmd+]	Next workspace
Ctrl+Cmd+[	Previous workspace
Cmd+Shift+W	Close workspace
Cmd+Shift+R	Rename workspace
Cmd+B	Toggle sidebar

Split panes

Shortcut	Action
Cmd+D	Split right
Cmd+Shift+D	Split down
Opt+Cmd+Arrow	Focus pane directionally
Cmd+Shift+H	Flash focused panel

Notifications

Shortcut	Action
Cmd+I	Show notifications panel
Cmd+Shift+U	Jump to latest unread

Browser

Shortcut	Action
Cmd+Shift+L	Open browser in split
Cmd+L	Focus address bar
Cmd+[	Back
Cmd+]	Forward
Cmd+R	Reload 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