Environment variables

Auto-set context variables for cmux automation

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:

1. --password CLI flag (highest)
2. CMUX_SOCKET_PASSWORD environment variable
3. 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