Skip to main content
cmux provides powerful automation capabilities through its CLI tool and JSON-RPC socket protocol. You can control windows, workspaces, panes, surfaces, send text, read screen output, manage notifications, and automate browser interactions.

​
Quick start

Open a directory in cmux: 
cmux ~/projects/my-app
Create a new workspace and run a command: 
cmux new-workspace --cwd ~/projects --command "npm run dev"
Send text to the current terminal: 
echo "git status" | cmux send
Read the terminal screen: 
cmux read-screen --scrollback

​
Use cases

cmux is designed for AI coding agents. The CLI and socket API enable agents to:
  • Create workspaces for different tasks
  • Send commands and read output
  • Receive notifications when long-running processes complete
  • Automate browser testing and web scraping
  • Monitor multiple terminals simultaneously
Automate development workflows:
  • Start dev servers in dedicated workspaces
  • Run tests and collect results
  • Monitor logs across multiple services
  • Trigger notifications on build completion
Manage infrastructure and deployments:
  • SSH to multiple servers in split panes
  • Monitor deployment status
  • Automate kubectl commands
  • Stream logs from multiple pods
Control embedded browser surfaces:
  • Navigate to URLs and wait for page load
  • Click elements, fill forms, take screenshots
  • Extract text, HTML, or element properties
  • Run JavaScript and get results

​
Architecture

cmux exposes two automation interfaces:

​
CLI tool

The cmux command-line tool provides a convenient interface for automation:
  • Simple commands: cmux new-workspace, cmux send, cmux read-screen
  • JSON output: Add --json for machine-readable responses
  • Environment integration: Commands automatically target the current workspace/surface
  • Cross-platform: Works from any terminal or script
See CLI reference for all available commands.

​
Socket API

The underlying JSON-RPC socket protocol enables real-time control:
  • Event-driven: Subscribe to notifications, status changes, and errors
  • Low latency: Direct socket communication with no subprocess overhead
  • Batch operations: Send multiple commands in sequence
  • Custom clients: Build your own automation tools in any language
See Socket API for protocol details.

​
Environment variables

cmux automatically sets environment variables in terminals that identify the workspace and surface:
  • CMUX_WORKSPACE_ID: UUID of the current workspace
  • CMUX_SURFACE_ID: UUID of the current terminal surface
  • CMUX_SOCKET_PATH: Path to the control socket (default: /tmp/cmux.sock)
These allow commands like cmux send to automatically target the correct context without explicit flags. See Environment variables for details.

​
Authentication modes

cmux supports multiple socket authentication modes:

cmux processes only

Default mode. Only processes started inside cmux terminals can connect.

Automation mode

Allow external local automation clients from the same macOS user (no ancestry check).

Password mode

Require socket authentication with a password. Use --password flag or CMUX_SOCKET_PASSWORD env var.

Full open access

Allow any local process and user to connect with no auth. Unsafe - use only for testing.
Configure the socket mode in Settings or via the CMUX_SOCKET_MODE environment variable.

​
Handle formats

Most commands accept multiple handle formats for identifying resources:
  • UUIDs: a1b2c3d4-e5f6-7890-abcd-ef1234567890
  • Refs: window:1, workspace:2, pane:3, surface:4, tab:1
  • Indexes: 0, 1, 2 (0-based, depends on context)
By default, commands output refs. Use --id-format uuids or --id-format both to include UUIDs.

​
Next steps

CLI reference

Complete list of CLI commands and flags

Socket API

JSON-RPC protocol specification

Environment variables

Auto-set context variables