🤖 feat: add first-class mux run CLI command (#881)

## Summary

Replace the internal `agentSessionCli.ts` with a user-facing `mux run`
command for running agent sessions from the command line, with unified
logging across backend and CLI.

## Changes

### New `mux run` Command

```bash
# Simple usage
mux run "Fix the failing tests"

# With options
mux run --dir /path/to/project --runtime "ssh user@host" "Deploy changes"

# Scripted
echo "Add logging" | mux run --json | jq '.type'
```

**Key improvements over the old CLI:**

| Old (`agentSessionCli.ts`) | New (`mux run`) |
|---------------------------|-----------------| 
| `--workspace-path X --workspace-id Y` | Auto-derived from `--dir` |
| `--json-streaming` | `--json` |
| No `--help` | Full `--help` with examples |
| Buried in `debug/` | Top-level subcommand |
| `--thinking-level` | `-t, --thinking` |
| Timeout in ms only | `--timeout 5m` (human-friendly) |
| Very verbose output | Quiet by default (`--verbose` for info) |

### Unified Logging with Log Levels

- **Log levels**: `error`, `warn`, `info`, `debug` (hierarchical)
- **CLI default**: `error` (quiet - only errors shown)
- **Desktop default**: `info` (current behavior preserved)
- **Environment override**: `MUX_LOG_LEVEL=warn` or `MUX_DEBUG=1`

```bash
# Quiet by default
mux run "task"

# Verbose output
mux run --verbose "task"

# Explicit level
mux run --log-level debug "task"
```

Migrated ~30 files from raw `console.error/warn/log` to unified `log.*`
calls.

### CLI Routing with Commander.js

Top-level routing uses Commander.js with lazy loading to avoid importing
Electron/AI SDK until needed:
- `mux run` - agent sessions
- `mux server` - oRPC server
- `mux api` - API utilities  
- `mux desktop` - launch GUI (auto-detected when running under Electron)

### Other Improvements

- **Default model**: Centralized to Opus 4.5 (`DEFAULT_MODEL` constant)
- **Timeout parsing**: Uses `parse-duration` library for robust handling
(`1h30m`, `5min`, etc.)
- **Terminal-bench**: Updated to use new CLI entry point

## Testing

- CLI integration tests in `src/cli/run.test.ts`
- All static checks pass
- E2E tests updated for new default model

---

_Generated with `mux`_

Author: ammar-agent

benchmarks/terminal_bench/mux-run.sh

@@ -29,6 +29,7 @@ MUX_TRUNK="${MUX_TRUNK:-main}"
 MUX_WORKSPACE_ID="${MUX_WORKSPACE_ID:-mux-bench}"
 MUX_THINKING_LEVEL="${MUX_THINKING_LEVEL:-high}"
 MUX_MODE="${MUX_MODE:-exec}"
+MUX_RUNTIME="${MUX_RUNTIME:-}"
 
 resolve_project_path() {
   if [[ -n "${MUX_PROJECT_PATH}" ]]; then
@@ -77,21 +78,21 @@ ensure_git_repo "${project_path}"
 log "starting mux agent session for ${project_path}"
 cd "${MUX_APP_ROOT}"
 
-cmd=(bun src/cli/debug/agentSessionCli.ts
-  --config-root "${MUX_CONFIG_ROOT}"
-  --project-path "${project_path}"
-  --workspace-path "${project_path}"
-  --workspace-id "${MUX_WORKSPACE_ID}"
+cmd=(bun src/cli/run.ts
+  --dir "${project_path}"
   --model "${MUX_MODEL}"
   --mode "${MUX_MODE}"
-  --json-streaming)
+  --thinking "${MUX_THINKING_LEVEL}"
+  --config-root "${MUX_CONFIG_ROOT}"
+  --workspace-id "${MUX_WORKSPACE_ID}"
+  --json)
 
 if [[ -n "${MUX_TIMEOUT_MS}" ]]; then
   cmd+=(--timeout "${MUX_TIMEOUT_MS}")
 fi
 
-if [[ -n "${MUX_THINKING_LEVEL}" ]]; then
-  cmd+=(--thinking-level "${MUX_THINKING_LEVEL}")
+if [[ -n "${MUX_RUNTIME}" ]]; then
+  cmd+=(--runtime "${MUX_RUNTIME}")
 fi
 
 # Terminal-bench enforces timeouts via --global-agent-timeout-sec

benchmarks/terminal_bench/mux_agent.py

@@ -62,6 +62,7 @@ class MuxAgent(AbstractInstalledAgent):
         "MUX_APP_ROOT",
         "MUX_WORKSPACE_ID",
         "MUX_MODE",
+        "MUX_RUNTIME",
     )
 
     def __init__(

bun.lock

@@ -48,6 +48,7 @@
         "motion": "^12.23.24",
         "ollama-ai-provider-v2": "^1.5.4",
         "openai": "^6.9.1",
+        "parse-duration": "^2.1.4",
         "rehype-harden": "^1.1.5",
         "shescape": "^2.1.6",
         "source-map-support": "^0.5.21",
@@ -2937,6 +2938,8 @@
 
     "parent-module": ["parent-module@1.0.1", "", { "dependencies": { "callsites": "^3.0.0" } }, "sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g=="],
 
+    "parse-duration": ["parse-duration@2.1.4", "", {}, "sha512-b98m6MsCh+akxfyoz9w9dt0AlH2dfYLOBss5SdDsr9pkhKNvkWBXU/r8A4ahmIGByBOLV2+4YwfCuFxbDDaGyg=="],
+
     "parse-entities": ["parse-entities@4.0.2", "", { "dependencies": { "@types/unist": "^2.0.0", "character-entities-legacy": "^3.0.0", "character-reference-invalid": "^2.0.0", "decode-named-character-reference": "^1.0.0", "is-alphanumerical": "^2.0.0", "is-decimal": "^2.0.0", "is-hexadecimal": "^2.0.0" } }, "sha512-GG2AQYWoLgL877gQIKeRPGO1xF9+eG1ujIb5soS5gPvLQ1y2o8FL90w2QWNdf9I361Mpp7726c+lj3U0qK1uGw=="],
 
     "parse-json": ["parse-json@5.2.0", "", { "dependencies": { "@babel/code-frame": "^7.0.0", "error-ex": "^1.3.1", "json-parse-even-better-errors": "^2.3.0", "lines-and-columns": "^1.1.6" } }, "sha512-ayCKvm/phCGxOkYRSCM82iDwct8/EonSEgCSxWxD7ve6jHggsFl4fZVQBPRNgQoKiuV/odhFrGzQXZwbifC8Rg=="],

docs/SUMMARY.md

@@ -4,6 +4,7 @@
 
 - [Introduction](./intro.md)
 - [Install](./install.md)
+- [CLI](./cli.md)
 - [Why Parallelize?](./why-parallelize.md)
 
 # Features

docs/benchmarking.md

@@ -18,6 +18,7 @@ Optional environment overrides:
 | `MUX_MODEL`           | Preferred model (supports `provider/model` syntax)        | `anthropic/claude-sonnet-4-5`          |
 | `MUX_THINKING_LEVEL`  | Optional reasoning level (`off`, `low`, `medium`, `high`) | `high`                                 |
 | `MUX_MODE`            | Starting mode (`plan` or `exec`)                          | `exec`                                 |
+| `MUX_RUNTIME`         | Runtime type (`local`, `worktree`, or `ssh <host>`)       | `worktree`                             |
 | `MUX_TIMEOUT_MS`      | Optional stream timeout in milliseconds                   | no timeout                             |
 | `MUX_CONFIG_ROOT`     | Location for mux session data inside the container        | `/root/.mux`                           |
 | `MUX_APP_ROOT`        | Path where the mux sources are staged                     | `/opt/mux-app`                         |
@@ -65,7 +66,7 @@ The adapter lives in `benchmarks/terminal_bench/mux_agent.py`. For each task it:
 
 1. Copies the mux repository (package manifests + `src/`) into `/tmp/mux-app` inside the container.
 2. Ensures Bun exists, then runs `bun install --frozen-lockfile`.
-3. Launches `src/cli/debug/agentSessionCli.ts` to prepare workspace metadata and stream the instruction, storing state under `MUX_CONFIG_ROOT` (default `/root/.mux`).
+3. Launches `mux run` (`src/cli/run.ts`) to prepare workspace metadata and stream the instruction, storing state under `MUX_CONFIG_ROOT` (default `/root/.mux`).
 
 `MUX_MODEL` accepts either the mux colon form (`anthropic:claude-sonnet-4-5`) or the Terminal-Bench slash form (`anthropic/claude-sonnet-4-5`); the adapter normalises whichever you provide.
 

docs/cli.md

@@ -0,0 +1,101 @@
+# Command Line Interface
+
+Mux provides a CLI for running one-off agent tasks without the desktop app. Unlike the interactive desktop experience, `mux run` executes a single request to completion and exits.
+
+## `mux run`
+
+Execute a one-off agent task:
+
+```bash
+# Basic usage - run in current directory
+mux run "Fix the failing tests"
+
+# Specify a directory
+mux run --dir /path/to/project "Add authentication"
+
+# Use SSH runtime
+mux run --runtime "ssh user@myserver" "Deploy changes"
+
+# Pipe instructions via stdin
+echo "Add logging to all API endpoints" | mux run
+
+# JSON output for scripts
+mux run --json "List all TypeScript files" | jq '.type'
+```
+
+### Options
+
+| Option                 | Short | Description                                        | Default           |
+| ---------------------- | ----- | -------------------------------------------------- | ----------------- |
+| `--dir <path>`         | `-d`  | Project directory                                  | Current directory |
+| `--model <model>`      | `-m`  | Model to use (e.g., `anthropic:claude-sonnet-4-5`) | Default model     |
+| `--runtime <runtime>`  | `-r`  | Runtime: `local`, `worktree`, or `ssh <host>`      | `local`           |
+| `--mode <mode>`        |       | Agent mode: `plan` or `exec`                       | `exec`            |
+| `--thinking <level>`   | `-t`  | Thinking level: `off`, `low`, `medium`, `high`     | `medium`          |
+| `--timeout <duration>` |       | Timeout (e.g., `5m`, `300s`, `300000`)             | No timeout        |
+| `--json`               |       | Output NDJSON for programmatic use                 | Off               |
+| `--quiet`              | `-q`  | Only output final result                           | Off               |
+| `--workspace-id <id>`  |       | Explicit workspace ID                              | Auto-generated    |
+| `--config-root <path>` |       | Mux config directory                               | `~/.mux`          |
+
+### Runtimes
+
+- **`local`** (default): Runs directly in the specified directory. Best for one-off tasks.
+- **`worktree`**: Creates an isolated git worktree under `~/.mux/src`. Useful for parallel work.
+- **`ssh <host>`**: Runs on a remote machine via SSH. Example: `--runtime "ssh user@myserver.com"`
+
+### Output Modes
+
+- **Default (TTY)**: Human-readable streaming with tool call formatting
+- **`--json`**: NDJSON streaming - each line is a JSON object with event data
+- **`--quiet`**: Suppresses streaming output, only shows final assistant response
+
+### Examples
+
+```bash
+# Quick fix in current directory
+mux run "Fix the TypeScript errors"
+
+# Use a specific model with extended thinking
+mux run -m anthropic:claude-sonnet-4-5 -t high "Optimize database queries"
+
+# Run on remote server
+mux run -r "ssh dev@staging.example.com" -d /app "Update dependencies"
+
+# Scripted usage with timeout
+mux run --json --timeout 5m "Generate API documentation" > output.jsonl
+```
+
+## `mux server`
+
+Start the HTTP/WebSocket server for remote access (e.g., from mobile devices):
+
+```bash
+mux server --port 3000 --host 0.0.0.0
+```
+
+Options:
+
+- `--host <host>` - Host to bind to (default: `localhost`)
+- `--port <port>` - Port to bind to (default: `3000`)
+- `--auth-token <token>` - Optional bearer token for authentication
+- `--add-project <path>` - Add and open project at the specified path
+
+## `mux desktop`
+
+Launch the desktop app. This is automatically invoked when running the packaged app or via `electron .`:
+
+```bash
+mux desktop
+```
+
+Note: Requires Electron. When running `mux` with no arguments under Electron, the desktop app launches automatically.
+
+## `mux --version`
+
+Print the version and git commit:
+
+```bash
+mux --version
+# v0.8.4 (abc123)
+```

package.json

@@ -89,6 +89,7 @@
     "motion": "^12.23.24",
     "ollama-ai-provider-v2": "^1.5.4",
     "openai": "^6.9.1",
+    "parse-duration": "^2.1.4",
     "rehype-harden": "^1.1.5",
     "shescape": "^2.1.6",
     "source-map-support": "^0.5.21",

scripts/check-bench-agent.sh

@@ -15,7 +15,7 @@ if [[ ! -f "$MUX_RUN_SH" ]]; then
 fi
 
 # Extract the agent CLI path from mux-run.sh
-# Looks for line like: cmd=(bun src/cli/debug/agentSessionCli.ts
+# Looks for line like: cmd=(bun src/cli/run.ts
 CLI_PATH_MATCH=$(grep -o "bun src/.*\.ts" "$MUX_RUN_SH" | head -1 | cut -d' ' -f2)
 
 if [[ -z "$CLI_PATH_MATCH" ]]; then

src/browser/stories/mockFactory.ts

@@ -16,6 +16,7 @@ import type {
   MuxImagePart,
   MuxToolPart,
 } from "@/common/types/message";
+import { DEFAULT_MODEL } from "@/common/constants/knownModels";
 
 /** Part type for message construction */
 type MuxPart = MuxTextPart | MuxReasoningPart | MuxImagePart | MuxToolPart;
@@ -196,7 +197,7 @@ export function createAssistantMessage(
     metadata: {
       historySequence: opts.historySequence,
       timestamp: opts.timestamp ?? STABLE_TIMESTAMP,
-      model: opts.model ?? "anthropic:claude-sonnet-4-5",
+      model: opts.model ?? DEFAULT_MODEL,
       usage: { inputTokens: 100, outputTokens: 50, totalTokens: 150 },
       duration: 1000,
     },

src/browser/stories/storyHelpers.ts

@@ -14,6 +14,7 @@ import {
   getInputKey,
   getModelKey,
 } from "@/common/constants/storage";
+import { DEFAULT_MODEL } from "@/common/constants/knownModels";
 import {
   createWorkspace,
   groupWorkspacesByProject,
@@ -178,7 +179,7 @@ export function setupStreamingChatStory(opts: StreamingChatSetupOptions): APICli
       createStreamingChatHandler({
         messages: opts.messages,
         streamingMessageId: opts.streamingMessageId,
-        model: opts.model ?? "anthropic:claude-sonnet-4-5",
+        model: opts.model ?? DEFAULT_MODEL,
         historySequence: opts.historySequence,
         streamText: opts.streamText,
         pendingTool: opts.pendingTool,