🤖 feat: add first-class mux run CLI command

Replace the internal agentSessionCli.ts with a user-facing `mux run` command:

- Add `mux run` subcommand with Commander.js for proper --help
- Smart defaults: local runtime, medium thinking, auto-generated workspace ID
- Human-friendly timeout parsing (5m, 300s, etc.)
- Clean flag names (--json, --thinking, --dir)
- Full documentation in docs/cli.md

Update terminal-bench to use the new entry point:
- benchmarks/terminal_bench/mux-run.sh now invokes src/cli/run.ts
- Simpler invocation with fewer verbose flags

Usage:
  mux run "Fix the tests"
  mux run --dir /project --runtime "ssh user@host" "Deploy"
  echo "Add logging" | mux run --json

_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__(

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,97 @@
+# Command Line Interface
+
+Mux provides a CLI for running agent sessions without opening the desktop app.
+
+## `mux run`
+
+Run an agent session in any directory:
+
+```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"
+
+# Plan mode (proposes a plan, then auto-executes)
+mux run --mode plan "Refactor the auth module"
+
+# 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
+
+# Plan first, then execute
+mux run --mode plan "Migrate from REST to GraphQL"
+```
+
+## `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 version`
+
+Print the version and git commit:
+
+```bash
+mux version
+# mux v0.8.4 (abc123)
+```

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/cli/index.ts

@@ -7,6 +7,11 @@ if (subcommand === "server") {
   process.argv.splice(2, 1);
   // eslint-disable-next-line @typescript-eslint/no-require-imports
   require("./server");
+} else if (subcommand === "run") {
+  // Remove 'run' from args since run.ts uses Commander which handles its own parsing
+  process.argv.splice(2, 1);
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  require("./run");
 } else if (subcommand === "version") {
   // eslint-disable-next-line @typescript-eslint/no-require-imports
   const { VERSION } = require("../version") as {