Environment variables

cmux automatically sets environment variables in terminals that identify the workspace, surface, and socket path. This enables CLI commands and scripts to automatically target the correct context.

Auto-set variables

These variables are automatically set in all cmux terminal surfaces:

CMUX_WORKSPACE_ID

UUID of the current workspace. Example value:

a1b2c3d4-e5f6-7890-abcd-ef1234567890

Usage:

# Commands automatically use current workspace
cmux send git status
cmux list-panels
cmux new-split right

# Explicitly reference from scripts
echo "Current workspace: $CMUX_WORKSPACE_ID"

Most CLI commands use CMUX_WORKSPACE_ID as the default --workspace value when not explicitly provided.

CMUX_SURFACE_ID

UUID of the current terminal surface (also called “panel” or “tab”). Example value:

b2c3d4e5-f6a7-8901-bcde-f12345678901

Usage:

# Commands automatically target current surface
cmux send echo hello
cmux read-screen --scrollback
cmux close-surface

# Reference from scripts
echo "Current surface: $CMUX_SURFACE_ID"

Commands like send, read-screen, and close-surface use CMUX_SURFACE_ID as the default --surface value.

CMUX_TAB_ID

Optional alias for CMUX_SURFACE_ID, used by tab-action and rename-tab as the default --tab value. Usage:

cmux tab-action --action rename --title "My Tab"
cmux rename-tab New Name

CMUX_SOCKET_PATH

Path to the control socket for the running cmux instance. Default values:

Production: /tmp/cmux.sock
Debug build: /tmp/cmux-debug.sock
Nightly: /tmp/cmux-nightly.sock
Staging: /tmp/cmux-staging.sock

Usage:

# CLI automatically uses correct socket
cmux list-workspaces

# Custom socket clients
echo '{"id":"1","method":"workspace.list","params":{}}' | \
  nc -U "$CMUX_SOCKET_PATH"

The --socket CLI flag and custom clients should read CMUX_SOCKET_PATH to connect to the correct instance.

Configuration variables

These variables configure cmux behavior:

CMUX_SOCKET_MODE

Override the socket authentication mode. Values:

off: Disable socket
cmuxonly / cmux-only: Only cmux processes (default)
automation: Allow external automation clients
password: Require password authentication
allowall / allow-all / fullopenaccess: Full open access (unsafe)

Example:

export CMUX_SOCKET_MODE=automation
open -a cmux

CMUX_SOCKET_ENABLE

Enable or disable the socket. Values:

1, true, yes, on: Enable
0, false, no, off: Disable

Example:

export CMUX_SOCKET_ENABLE=0
open -a cmux  # socket disabled

CMUX_SOCKET_PASSWORD

Socket password for authentication (when password mode is enabled). Precedence:

--password CLI flag (highest)
CMUX_SOCKET_PASSWORD environment variable
Password file: ~/Library/Application Support/cmux/socket-control-password

Example:

export CMUX_SOCKET_PASSWORD="my-secret-password"
cmux --socket /tmp/cmux.sock list-workspaces

Store passwords securely. Avoid hardcoding passwords in scripts. Use the password file for persistent storage.

CMUX_ALLOW_SOCKET_OVERRIDE

Allow CMUX_SOCKET_PATH to override the default socket path. Values:

1, true, yes, on: Allow override

Default behavior:

Debug/staging builds: Always allow override
Production build: Require explicit CMUX_ALLOW_SOCKET_OVERRIDE=1

Example:

export CMUX_ALLOW_SOCKET_OVERRIDE=1
export CMUX_SOCKET_PATH=/tmp/my-custom.sock
open -a cmux

CMUX_TAG

Launch tag for parallel/isolated debug builds. Usage:

export CMUX_TAG=feature-test
open -a "cmux DEV"
# Creates isolated app with:
# - Name: "cmux DEV (feature-test)"
# - Bundle ID: com.cmuxterm.app.debug.feature-test
# - Socket: /tmp/cmux-debug-feature-test.sock

Tags are used by the ./scripts/reload.sh --tag <name> script for parallel development.

Debugging variables

CMUX_CLI_SENTRY_DISABLED

Disable CLI Sentry diagnostics. Values:

1: Disable Sentry

Example:

export CMUX_CLI_SENTRY_DISABLED=1
cmux list-workspaces

CMUX_CLAUDE_HOOK_SENTRY_DISABLED

Disable Claude hook Sentry diagnostics. Values:

1: Disable Sentry

Example:

export CMUX_CLAUDE_HOOK_SENTRY_DISABLED=1
cmux claude-hook session-start

CMUX_CLAUDE_HOOK_STATE_PATH

Override Claude hook session state file path. Default:

~/.cmuxterm/claude-hook-sessions.json

Example:

export CMUX_CLAUDE_HOOK_STATE_PATH=~/custom-hook-state.json

CMUXTERM_CLI_RESPONSE_TIMEOUT_SEC

CLI socket response timeout in seconds. Default:

15.0

Example:

export CMUXTERM_CLI_RESPONSE_TIMEOUT_SEC=30
cmux browser wait --timeout 25

Shell integration

Add these to your shell profile for enhanced automation:

Bash/Zsh

~/.bashrc or ~/.zshrc

# Quick workspace info
alias ws='echo "Workspace: $CMUX_WORKSPACE_ID"'
alias surf='echo "Surface: $CMUX_SURFACE_ID"'

# Notify on command completion
notify() {
  "$@"
  local exit_code=$?
  if [ $exit_code -eq 0 ]; then
    cmux notify --title "Command complete" --body "$*"
  else
    cmux notify --title "Command failed" --body "$* (exit $exit_code)"
  fi
  return $exit_code
}

# Example: notify npm run build

Fish

~/.config/fish/config.fish

# Quick workspace info
alias ws='echo "Workspace: $CMUX_WORKSPACE_ID"'
alias surf='echo "Surface: $CMUX_SURFACE_ID"'

# Notify on command completion
function notify
    $argv
    set exit_code $status
    if test $exit_code -eq 0
        cmux notify --title "Command complete" --body "$argv"
    else
        cmux notify --title "Command failed" --body "$argv (exit $exit_code)"
    end
    return $exit_code
end

Script examples

Multi-workspace build script

#!/bin/bash
# build-all.sh - Build multiple projects in parallel

PROJECTS=("frontend" "backend" "api")

for project in "${PROJECTS[@]}"; do
  ws_id=$(cmux new-workspace --cwd "~/projects/$project" --json | jq -r '.workspace_id')
  cmux send --workspace "$ws_id" "npm run build"
  cmux set-status --workspace "$ws_id" build "Building..." --icon "⚙️"
done

echo "Started builds in ${#PROJECTS[@]} workspaces"

Monitor and notify

#!/bin/bash
# watch-tests.sh - Monitor test output and notify on completion

WORKSPACE=${CMUX_WORKSPACE_ID}

while true; do
  OUTPUT=$(cmux read-screen --workspace "$WORKSPACE" --lines 10)
  
  if echo "$OUTPUT" | grep -q "Tests: .* passed"; then
    cmux notify --workspace "$WORKSPACE" \
      --title "Tests Passed" \
      --body "All tests completed successfully"
    break
  elif echo "$OUTPUT" | grep -q "Tests: .* failed"; then
    cmux notify --workspace "$WORKSPACE" \
      --title "Tests Failed" \
      --body "Some tests failed"
    break
  fi
  
  sleep 2
done

Context-aware automation

#!/bin/bash
# smart-deploy.sh - Deploy based on current workspace

if [ -z "$CMUX_WORKSPACE_ID" ]; then
  echo "Not running in cmux - creating workspace"
  WORKSPACE=$(cmux new-workspace --cwd . --json | jq -r '.workspace_id')
else
  echo "Using current workspace: $CMUX_WORKSPACE_ID"
  WORKSPACE=$CMUX_WORKSPACE_ID
fi

cmux set-progress --workspace "$WORKSPACE" 0.0 --label "Starting deploy"
cmux send --workspace "$WORKSPACE" "npm run deploy"

for i in {1..10}; do
  cmux set-progress --workspace "$WORKSPACE" "0.${i}" --label "Deploying..."
  sleep 1
done

cmux set-progress --workspace "$WORKSPACE" 1.0 --label "Complete"
cmux clear-progress --workspace "$WORKSPACE"
cmux notify --workspace "$WORKSPACE" --title "Deploy Complete"

Best practices

Always check for cmux context

Check if CMUX_WORKSPACE_ID is set before assuming you’re in a cmux terminal:

if [ -z "$CMUX_WORKSPACE_ID" ]; then
  echo "Not running in cmux"
  exit 1
fi

Use --json for machine parsing

Always use --json flag when parsing CLI output in scripts:

ws_id=$(cmux new-workspace --json | jq -r '.workspace_id')

Handle missing variables gracefully

Provide fallbacks for missing environment variables:

WORKSPACE=${CMUX_WORKSPACE_ID:-$(cmux current-workspace)}
SOCKET=${CMUX_SOCKET_PATH:-/tmp/cmux.sock}

Use explicit IDs for non-local operations

When operating on resources outside the current workspace, always specify explicit IDs:

# Good: explicit workspace
cmux send --workspace workspace:2 "echo hello"

# Bad: assumes current workspace
cmux send "echo hello"  # works locally but not in scripts

Get Started

Core Features

Automation

Integrations

Configuration

Environment variables

Auto-set variables

CMUX_WORKSPACE_ID

CMUX_SURFACE_ID

CMUX_TAB_ID

CMUX_SOCKET_PATH

Configuration variables

CMUX_SOCKET_MODE

CMUX_SOCKET_ENABLE

CMUX_SOCKET_PASSWORD

CMUX_ALLOW_SOCKET_OVERRIDE

CMUX_TAG

Debugging variables

CMUX_CLI_SENTRY_DISABLED

CMUX_CLAUDE_HOOK_SENTRY_DISABLED

CMUX_CLAUDE_HOOK_STATE_PATH

CMUXTERM_CLI_RESPONSE_TIMEOUT_SEC

Shell integration

Bash/Zsh

Fish

Script examples

Multi-workspace build script

Monitor and notify

Context-aware automation

Best practices

Build docs developers (and LLMs) love

Get Started

Core Features

Automation

Integrations

Configuration

Documentation Index

​Auto-set variables

​CMUX_WORKSPACE_ID

​CMUX_SURFACE_ID

​CMUX_TAB_ID

​CMUX_SOCKET_PATH

​Configuration variables

​CMUX_SOCKET_MODE

​CMUX_SOCKET_ENABLE

​CMUX_SOCKET_PASSWORD

​CMUX_ALLOW_SOCKET_OVERRIDE

​CMUX_TAG

​Debugging variables

​CMUX_CLI_SENTRY_DISABLED

​CMUX_CLAUDE_HOOK_SENTRY_DISABLED

​CMUX_CLAUDE_HOOK_STATE_PATH

​CMUXTERM_CLI_RESPONSE_TIMEOUT_SEC

​Shell integration

​Bash/Zsh

​Fish

​Script examples

​Multi-workspace build script

​Monitor and notify

​Context-aware automation

​Best practices

Build docs developers (and LLMs) love

Auto-set variables

CMUX_WORKSPACE_ID

CMUX_SURFACE_ID

CMUX_TAB_ID

CMUX_SOCKET_PATH

Configuration variables

CMUX_SOCKET_MODE

CMUX_SOCKET_ENABLE

CMUX_SOCKET_PASSWORD

CMUX_ALLOW_SOCKET_OVERRIDE

CMUX_TAG

Debugging variables

CMUX_CLI_SENTRY_DISABLED

CMUX_CLAUDE_HOOK_SENTRY_DISABLED

CMUX_CLAUDE_HOOK_STATE_PATH

CMUXTERM_CLI_RESPONSE_TIMEOUT_SEC

Shell integration

Bash/Zsh

Fish

Script examples

Multi-workspace build script

Monitor and notify

Context-aware automation

Best practices