Custom Commands: Let CMUX Remember Your Workflow

Do you do the same thing every time you start working: open a pane to run npm run dev, switch over to open a preview browser, then open another shell to keep handy? Three minutes gone, every single day.

CMUX custom commands are built to solve exactly this. Define your fixed work environment in cmux.json and restore the entire workspace layout with a single command.

Where Does cmux.json Go

Create a cmux.json in your project root directory. CMUX will automatically read it and add the commands defined inside to the available commands list.

Two Command Types

Workspace Command: Opens CMUX and creates a workspace with a pre-defined layout — terminals, browsers, split configuration all specified upfront. Ideal for "start of day" scenarios.

Simple Command: Runs a shell command without creating a workspace. Good for one-off operations like "run tests" or "initialize environment."

Workspace Command: Defining Your Dev Environment

Here's a complete example — one command that opens a Next.js dev server, a browser preview, and a backup shell all at once:

{
  "commands": [
    {
      "name": "Web Dev",
      "description": "Start Next.js and open preview",
      "keywords": ["web", "docs", "next", "frontend"],
      "restart": "confirm",
      "workspace": {
        "name": "Web Dev",
        "cwd": "./web",
        "color": "#3b82f6",
        "layout": {
          "direction": "horizontal",
          "split": 0.5,
          "children": [
            {
              "pane": {
                "surfaces": [
                  {
                    "type": "terminal",
                    "name": "Next.js",
                    "command": "npm run dev",
                    "focus": true
                  }
                ]
              }
            },
            {
              "direction": "vertical",
              "split": 0.6,
              "children": [
                {
                  "pane": {
                    "surfaces": [
                      {
                        "type": "browser",
                        "name": "Preview",
                        "url": "http://localhost:3777"
                      }
                    ]
                  }
                },
                {
                  "pane": {
                    "surfaces": [
                      {
                        "type": "terminal",
                        "name": "Shell",
                        "env": { "NODE_ENV": "development" }
                      }
                    ]
                  }
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

Breaking down the config:

• name / description: The label and description shown in the command list
• keywords: Used for search — type a keyword to find this command
• restart: If the workspace already exists, "confirm" asks whether to restart; "ignore" skips it
• workspace.cwd: The default working directory for this workspace
• workspace.color: The identifier color for this workspace in the sidebar
• layout: Defines the full layout structure

Layout logic: direction is the split direction ("horizontal" for left/right, "vertical" for top/bottom), split is the split ratio (0.5 means equal halves), and children contains the panes.

This example creates: Next.js running on the left half, browser preview on the upper right, backup shell on the lower right.

Simple Command: One-Off Operations

For operations that don't need a layout:

{
  "name": "Setup",
  "description": "Initialize submodules and build dependencies",
  "keywords": ["setup", "init", "install"],
  "command": "./scripts/setup.sh",
  "confirm": true
}

confirm: true means a confirmation prompt appears before execution — appropriate for destructive operations (clearing cache, reinstalling dependencies).

{
  "name": "Run Unit Tests",
  "keywords": ["test", "unit"],
  "command": "./scripts/test-unit.sh",
  "confirm": true
}

A Log Monitoring Workspace

Another common pattern — a workspace dedicated to log monitoring, running continuously in the background:

{
  "name": "Debug Log",
  "description": "Real-time debug event log monitoring",
  "keywords": ["log", "debug", "tail"],
  "restart": "ignore",
  "workspace": {
    "name": "Debug Log",
    "layout": {
      "direction": "horizontal",
      "split": 0.5,
      "children": [
        {
          "pane": {
            "surfaces": [
              {
                "type": "terminal",
                "name": "Events",
                "command": "tail -f /tmp/app-debug.log",
                "focus": true
              }
            ]
          }
        },
        {
          "pane": {
            "surfaces": [
              {
                "type": "terminal",
                "name": "Shell"
              }
            ]
          }
        }
      ]
    }
  }
}

The logic behind restart: "ignore": if this workspace is already running, leave it alone — let it keep monitoring.

A Few Design Principles

Think carefully about keywords: Once you have many commands, keywords is the only way to find them quickly. Include the verbs you'd naturally type, like ["start", "dev", "run"].

Use relative paths for cwd: ./web is better than /Users/yourname/projects/app/web — your config works across different machines without modification.

Use colors to categorize: Give different workspace types different colors — blue for development, orange for testing, gray for monitoring. A glance at the sidebar tells you everything.

Custom commands in place. The final article brings everything together into a real multi-agent workflow: Real-World Multi-Agent Workflow: CMUX Patterns for Actual Development.