Real-World Multi-Agent Workflow: CMUX Patterns for Actual Development

The previous five articles covered every functional block of CMUX individually. Now it's time to connect them — a real development scenario where you're running three AI Agents simultaneously, each needing its own space, where you receive completion notifications, and occasionally need to control terminal behavior through scripts.

The Scenario: Three Agents Running at Once

Say you have three things to do today:

One agent implementing a new feature (Claude Code / Cursor)
One running a CI-style test loop
One monitoring logs to make sure nothing's blowing up

These three are independent of each other, but all need to run — and you want to see the status of all of them at a glance.

Workspace Design

Following the "workspace = task" principle, create three workspaces:

Workspace Name	Color	Contents
`feature-auth`	Blue	Agent output + backup shell
`test-runner`	Orange	Test command output
`monitoring`	Gray	`tail -f` log monitoring

All three are fully independent — scan their status in the sidebar at any time.

cmux.json Design

Write all three workspaces as custom commands. Trigger them one by one at the start of the day, and all three environments come up together:

{
  "commands": [
    {
      "name": "Feature Dev",
      "description": "Auth feature development workspace",
      "keywords": ["feature", "auth", "dev"],
      "restart": "confirm",
      "workspace": {
        "name": "feature-auth",
        "color": "#3b82f6",
        "cwd": "./",
        "layout": {
          "direction": "horizontal",
          "split": 0.65,
          "children": [
            {
              "pane": {
                "surfaces": [
                  {
                    "type": "terminal",
                    "name": "Agent",
                    "focus": true
                  }
                ]
              }
            },
            {
              "pane": {
                "surfaces": [
                  {
                    "type": "terminal",
                    "name": "Shell"
                  }
                ]
              }
            }
          ]
        }
      }
    },
    {
      "name": "Test Runner",
      "description": "Continuous test execution",
      "keywords": ["test", "runner", "ci"],
      "restart": "ignore",
      "workspace": {
        "name": "test-runner",
        "color": "#f97316",
        "cwd": "./",
        "layout": {
          "direction": "horizontal",
          "split": 1,
          "children": [
            {
              "pane": {
                "surfaces": [
                  {
                    "type": "terminal",
                    "name": "Tests",
                    "command": "npm run test:watch",
                    "focus": true
                  }
                ]
              }
            }
          ]
        }
      }
    },
    {
      "name": "Monitoring",
      "description": "Log monitoring",
      "keywords": ["log", "monitor", "tail"],
      "restart": "ignore",
      "workspace": {
        "name": "monitoring",
        "color": "#6b7280",
        "cwd": "./",
        "layout": {
          "direction": "horizontal",
          "split": 0.5,
          "children": [
            {
              "pane": {
                "surfaces": [
                  {
                    "type": "terminal",
                    "name": "App Log",
                    "command": "tail -f logs/app.log",
                    "focus": true
                  }
                ]
              }
            },
            {
              "pane": {
                "surfaces": [
                  {
                    "type": "terminal",
                    "name": "Error Log",
                    "command": "tail -f logs/error.log"
                  }
                ]
              }
            }
          ]
        }
      }
    }
  ]
}

Sending Notifications via CLI

When an agent finishes a large task, you want a notification rather than staring at the output. Add this to your scripts or agent configuration:

# Notify on task completion
cmux notify --title "Feature Build Done" --body "auth feature build complete, ready for review"
 
# Warn on test failure
cmux notify --title "Test Failed" --body "3 tests failing, check the test-runner workspace"

If you're calling this from outside CMUX (e.g., a CI script), make sure the /usr/local/bin/cmux symlink is in place (see the installation article).

Socket API Automation: Advanced Usage

The socket API lets you control CMUX programmatically. Before using it, confirm the automation mode setting:

Preferences > Automation Mode > cmux processes only (recommended for personal dev machines)

Query all workspaces:

cmux list-workspaces

The output from this command can feed into scripts — enabling logic like "check whether a specific workspace exists, and create it automatically if it doesn't."

Working Rhythm Suggestions

Start of day: Trigger the three custom commands, all three workspaces come up together — no manual configuration required.

During work: While agents are running, you don't need to watch them constantly — wait for notifications. When one arrives, switch over to review the result.

Switching contexts: Three workspaces in the sidebar, one click to switch — no more hunting through windows with ⌘Tab.

End of day: Run cmux list-workspaces to verify all workspace statuses, making sure no agent is left mid-task.

Notes for Shared Machines

If your development machine is shared (team server, CI runner), set automation mode to "Disabled" or "cmux processes only" — never use allowAll in shared environments. The latter allows any local process to connect to your CMUX socket, which is a security risk in a shared context.

That completes the full CMUX workflow. From installation, structure, configuration, custom commands, to real-world multi-agent operation — a repeatable system that stays organized no matter how many agents you're running.

Want to revisit a specific topic? Head to the series overview and jump to the right article.