Skip to main content
cmux includes a WKWebView-based browser that can be split alongside terminals. The browser has a scriptable API ported from agent-browser for AI agent interaction.

​
Opening the browser

Create a browser surface:
  • Press ⌘ ⇧ L to open a browser in a split
  • Use the CLI: cmux new-pane --type browser
  • Click the browser split button in the UI
The browser opens in a new split pane next to your terminal.

​
Browser features

ShortcutAction
⌘ LFocus address bar
⌘ [Back
⌘ ]Forward
⌘ RReload page
The address bar supports:
  • Direct URL entry (http/https)
  • Search queries (uses configured search engine)
  • History suggestions
  • Autocomplete from browser history

​
Search engines

Configure your preferred search engine in Settings → Browser:
  • Google (default)
  • DuckDuckGo
  • Bing
  • Kagi
When you type a non-URL in the address bar, cmux searches using the selected engine.
Search suggestions are fetched from the search engine’s API and displayed as you type. You can disable this in Settings → Browser → Search Suggestions.

​
Developer tools

Access WebKit developer tools for debugging:
ShortcutAction
⌥ ⌘ IToggle Developer Tools
⌥ ⌘ CShow JavaScript Console
Developer tools open in a split pane below the browser, similar to Safari’s inspector.
Developer tools shortcuts follow Safari defaults and are customizable in Settings → Keyboard Shortcuts.

​
Browser theme

The browser adapts to Ghostty’s terminal theme:
  • Background color matches the terminal background
  • Supports transparent/translucent backgrounds
  • Light/dark mode based on system appearance or custom override
Change the browser theme mode in Settings → Browser → Theme:
  • System: Follow macOS appearance
  • Light: Force light mode
  • Dark: Force dark mode
Forced dark mode uses WKWebView’s content appearance API to render pages in dark mode even if the page doesn’t provide a dark theme.

​
Security and privacy

​
Insecure HTTP blocking

By default, cmux blocks insecure HTTP URLs except for localhost and common development hosts:
  • localhost
  • 127.0.0.1
  • ::1
  • 0.0.0.0
  • *.localtest.me
Add additional hosts to the allowlist in Settings → Browser → Insecure HTTP Allowlist. When you navigate to a blocked HTTP URL, cmux prompts:
  • “Allow Once” (one-time bypass)
  • “Always Allow” (add to persistent allowlist)
  • “Cancel”
Insecure HTTP connections are vulnerable to man-in-the-middle attacks. Only allow hosts you trust.
All browser panels share a WKProcessPool, meaning:
  • Cookies are shared across all browser tabs
  • You stay logged in when you split or create new browser surfaces
  • Session storage is shared within the same origin
Clear cookies and site data via WKWebView’s data store (not yet exposed in UI). By default, cmux intercepts terminal link clicks and opens them in the built-in browser:
  • Terminal links (Cmd+Click on URLs): Open in cmux browser
  • Sidebar PR links: Open in cmux browser
  • open command interception: Redirect open <url> to cmux browser
Disable these behaviors in Settings → Browser if you prefer using your default external browser.

​
Host whitelist

Restrict which hosts open in cmux browser vs. external browser using the host whitelist (Settings → Browser → Host Whitelist):
  • Empty whitelist = all hosts allowed
  • Add specific hosts (e.g., localhost, github.com)
  • Supports wildcards (e.g., *.vercel.app)
Hosts not in the whitelist open externally in your default browser.

​
Browser history

cmux maintains a local browser history store:
  • Persisted to ~/Library/Application Support/com.cmuxterm.app/browser_history.json
  • Stores URL, title, visit count, and last visited timestamp
  • Powers address bar autocomplete and suggestions
  • Automatically deduplicates URLs (ignores trailing slashes, www prefix)
History is shared across all browser surfaces in the app.

​
Clear history

Clear browser history in Settings → Browser → Clear History. This removes all stored URLs and resets autocomplete suggestions.

​
Scriptable API

The browser includes a scriptable API for AI agent interaction, ported from agent-browser:

​
Accessibility tree snapshot

Capture the accessibility tree for page structure: 
cmux browser snapshot
Returns a JSON representation of the page’s accessibility tree, useful for agents to understand page layout without parsing raw HTML.

​
Element interaction

Agents can interact with page elements: 
# Click an element by reference
cmux browser click --ref <element-ref>

# Fill a form field
cmux browser fill --ref <element-ref> --value "text"

# Evaluate JavaScript
cmux browser eval "document.title"
These commands use element references from the accessibility tree snapshot.
The scriptable API is designed for programmatic control by agents. For interactive browsing, use the standard keyboard shortcuts and mouse.

​
Page zoom

Zoom in/out on web pages:
  • Browser zoom is separate from terminal font zoom
  • Zoom level is saved per browser panel and restored on session reload
  • Defaults to 100% (1.0x)
Each browser panel maintains its own navigation history:
  • Back/forward buttons in the UI
  • Keyboard shortcuts ⌘ [ / ⌘ ]
  • History is saved in session state and restored on app relaunch
Navigation history includes:
  • Back history (pages you visited before current)
  • Forward history (pages you can go forward to)
  • Current URL
Closing and reopening the browser preserves navigation state.

​
Telemetry hooks

The browser injects JavaScript hooks to capture:
  • Console messages (log, info, warn, error, debug)
  • Unhandled errors and promise rejections
  • Dialog calls (alert, confirm, prompt)
These hooks are used internally for debugging and agent telemetry. They don’t send data externally.
Telemetry hooks are installed via content scripts and don’t interfere with normal page execution.