CLI Reference

Using mx from AI Agents

mx is designed to be called by AI coding agents. When working on multiple features or bug fixes in parallel, each task should run in its own Muxy workspace. This keeps terminal sessions, browser tabs, reserved ports, and editor windows fully isolated so the developer can switch context instantly without losing state.

A complete agent workflow — from a bare directory to a running workspace — looks like this:

1. 1. Add the project (mx project add).
2. 2. Configure ports, processes, status checks, browser sessions, and scripts via mx project port|process|status-check|browser-session and mx project update.
3. 3. Create a workspace for the branch or task (mx workspace create).
4. 4. Launch the workspace — ports are reserved, processes start, browser sessions open (mx workspace launch).
5. 5. Do the work. Switch context, run more workspaces in parallel.
6. 6. Archive the workspace when the task is done (mx workspace archive).

All commands print machine-readable output (tab-separated fields, no ANSI colour) and exit with a non-zero code on failure, making them safe to use in scripts and pipelines.

Finding the CLI

The mx binary ships inside the Muxy.app bundle. Muxy symlinks it to /usr/local/bin/mx when you first launch the app so it is available on $PATH immediately.

# Verify installation
mx --version

If the command is not found, open Muxy.app once — it will install the symlink.

Project Commands

Projects are codebases registered with Muxy. Register a project once, then create as many workspaces as you need from it.

List projects

mx project list

Prints one project per line: name, dir, git=yes|no, default_branch=<branch|->.

Add a project

# Register an existing local directory
mx project add --dir /path/to/repo

# Clone a remote git repo into ~/muxy/projects/ and register it
mx project add --git-url https://github.com/owner/repo.git

Muxy detects whether the directory is a Git repo and creates a non-archivable default workspace. For Git repos, each workspace gets its own worktree directory so parallel branches never share a working tree.

Set setup and stop scripts

mx project update --dir /path/to/repo \
  --setup-script "cp /shared/.env .env && npm install" \
  --stop-script "docker compose down --remove-orphans"

• --setup-script <cmd>Runs once when a workspace is created or revived from archive. Named port env vars are available.
• --stop-script <cmd>Runs after processes terminate on stop, restart, or archive.

Remove a project

mx project remove --dir /path/to/repo

Removes Muxy state, force-removes git worktrees, and deletes workspace directories under ~/muxy/workspaces. If the project was cloned via --git-url, its clone under ~/muxy/projects is also deleted.

Port Commands

Named ports are environment variables backed by real port numbers. Muxy allocates a unique port number from the configured range for each workspace, so two workspaces running at the same time never collide on the same local port. The allocated port is reserved via an OS socket for the lifetime of the workspace and injected as an env var into setup scripts, stop scripts, process commands, and status check commands.

mx project port list   --dir /path/to/repo
mx project port add    --dir /path/to/repo --name FRONTEND_PORT
mx project port add    --dir /path/to/repo --name API_PORT
mx project port remove --dir /path/to/repo --name API_PORT

Port names become env vars: $FRONTEND_PORT, $API_PORT, etc. Names must be valid shell identifier strings (uppercase by convention).

Process Commands

Processes are shell commands started in iTerm2 when a workspace launches. Named port env vars and MUXY_WORKSPACE_DIR / MUXY_PROJECT_DIR are injected automatically.

mx project process list   --dir /path/to/repo
mx project process add    --dir /path/to/repo --name frontend --command "PORT=$FRONTEND_PORT npm run dev"
mx project process add    --dir /path/to/repo --name docker   --command "docker compose up --build" --on-exit restart
mx project process add    --dir /path/to/repo --name api      --command "PORT=$API_PORT npm run api"
mx project process remove --dir /path/to/repo --name api

• --name <name>Process identifier. Used to associate status checks and for display in the run tab.
• --command <cmd>Shell command to execute. Named port env vars are available.
• --on-exit <action>Action when process exits: none | restart | notify. Default: none.

--on-exit restart attempts a clean terminate/wait of the previous runtime PID before relaunching.

Status Check Commands

Status checks run a shell command on a schedule while the workspace is running and surface green / red health in the Muxy run tab, nested under the associated process.

mx project status-check list   --dir /path/to/repo
mx project status-check add    --dir /path/to/repo \
  --name web-health \
  --process frontend \
  --command "curl -fsS http://localhost:$FRONTEND_PORT/health" \
  --interval 10 \
  --timeout 2 \
  --on-fail notify
mx project status-check remove --dir /path/to/repo --name web-health

• --name <name>Check identifier. Required for remove.
• --process <name>Name of the process this check is associated with.
• --command <cmd>Shell command to run. Exit 0 = healthy, non-zero = unhealthy.
• --interval <seconds>Seconds between runs. Default: 60.
• --timeout <seconds>Seconds before the command is killed. Default: 5.
• --on-fail <action>Action when the check fails: none | restart | notify. Default: none.

--on-fail restart marks the check red and restarts the associated process; --on-fail notify keeps the process running and sends a desktop notification.

Browser Session Commands

Browser sessions are URLs opened in Google Chrome when the workspace launches. Muxy tracks the tabs and reuses or reopens them on subsequent launches so the same pages come back without manual navigation. Named port env vars are resolved at launch time.

mx project browser-session list   --dir /path/to/repo
mx project browser-session add    --dir /path/to/repo --url "http://localhost:$FRONTEND_PORT"
mx project browser-session add    --dir /path/to/repo --url "http://localhost:$API_PORT/docs"
mx project browser-session remove --dir /path/to/repo --url "http://localhost:$API_PORT/docs"

Workspace Commands

A workspace is an isolated stream of work. For Git projects each workspace corresponds to a branch and a git worktree directory. Multiple workspaces can run at the same time.

List workspaces

# List non-archived workspaces
mx workspace list --project-dir /path/to/repo

# Include archived workspaces
mx workspace list --project-dir /path/to/repo --all

Output columns: name, dir, flags (default, running, archived).

Create a workspace

# Git project — create workspace on a new branch
mx workspace create \
  --project-dir /path/to/repo \
  --name "feat-auth" \
  --branch feat/auth \
  --target-branch main

# Git project — override worktree directory name
mx workspace create \
  --project-dir /path/to/repo \
  --name "fix-login-crash" \
  --branch fix/login-crash \
  --dirname fix_login_crash

# Non-git project
mx workspace create \
  --project-dir /path/to/project \
  --name "experiment-1"

• --name <name>Workspace display name used in the UI and in other commands.
• --branch <branch>Git branch name. Created from --target-branch if it does not exist. Required for git projects.
• --target-branch <branch>Base branch for the new branch. Defaults to main or master.
• --dirname <name>Override the git worktree directory name. Letters, numbers, - and _ only.
• --tooltip <text>Optional context about what you're working on. Display with cmd+shift+i global hotkey.

On creation, the workspace snapshots port definitions, processes, status checks, and browser sessions from the project config. Port numbers are allocated and the setup_script runs with those port env vars already set.

Import existing worktree

# Import workspace from current directory (infers name from branch)
mx workspace import

# Import workspace from specific worktree path
mx workspace import --dir /path/to/worktree

# Import workspace with custom title and tooltip
mx workspace import --dir /path/to/worktree --title "my-workspace" --tooltip "Working on OAuth integration"

Registers an existing git worktree as a Muxy workspace. The project must already be registered. Muxy infers the workspace title from the branch name if not provided. Port numbers are allocated and the setup_script runs immediately.

Discover and auto-create workspaces

# Discover all worktrees across all registered projects
mx discover

Reconciles git worktrees for all registered projects: creates workspaces for newly discovered worktrees, archives non-default workspaces whose worktrees are no longer valid, and refreshes stored branch names from disk. Useful for bulk-importing existing worktrees or syncing after manual git worktree operations.

Update workspace metadata

# Update title from current workspace directory
mx workspace update --title "feat-auth-v2"

# Update branch and directory name
mx workspace update --dir /path/to/workspace --branch fix-login-timeout --directory-name fix_login_timeout

# Set or clear tooltip text
mx workspace update --dir /path/to/workspace --tooltip "Working on OAuth integration"
mx workspace update --dir /path/to/workspace --clear-tooltip

Updates workspace metadata without launching/stopping runtime: title, branch, directory-name metadata, and tooltip text. Default workspaces keep their fixed title.

Launch a workspace

# Launch from current directory
mx workspace launch

# Launch from specific workspace directory
mx workspace launch --dir /path/to/workspace

Starts configured processes in iTerm2, opens browser sessions in Chrome, and opens the preferred editor. Only valid for stopped workspaces. When run without arguments, uses the current directory to identify the workspace.

Stop a workspace

# Stop from current directory
mx workspace stop

# Stop specific workspace
mx workspace stop --dir /path/to/workspace

Restart a workspace

# Restart from current directory
mx workspace restart

# Restart specific workspace
mx workspace restart --dir /path/to/workspace

Stops then immediately launches. Useful after a dependency install or config change.

Ensure a workspace is running

# Ensure running from current directory
mx workspace up

# Ensure running for a specific workspace
mx workspace up --dir /path/to/workspace

# Ensure running and force restart if already running/stale
mx workspace up --dir /path/to/workspace --restart

# Ensure running, focus, and show tooltip overlay
mx workspace up --dir /path/to/workspace --tooltip "Reviewing auth callback"

Idempotent run command: launches when stopped. If already running (or runtime indicators exist), it does nothing by default; pass --restart to run stop then launch. In all cases, Muxy focuses the workspace once running. With --tooltip [text], Muxy shows the tooltip overlay after focus and updates tooltip text when text is provided.

Archive a workspace

# Archive from current directory
mx workspace archive

# Archive specific workspace
mx workspace archive --dir /path/to/workspace

Stops the workspace, releases reserved ports, and marks it archived. Use --all on workspace list to see archived workspaces.

Focus a workspace

# Focus from current directory
mx workspace focus

# Focus specific workspace
mx workspace focus --dir /path/to/workspace

# Focus specific window index in the workspace
mx workspace focus --dir /path/to/workspace --window 2

Brings the workspace windows to the front so the developer can immediately resume work. Tooltip updates are managed with mx workspace update --tooltip ... or mx workspace up --tooltip ....

Settings Commands

GUI keyboard shortcuts can be read, overridden, or reset from the CLI. Hotkey specs use the format cmd+shift+x.

# Read
mx settings get --gui-hotkey
mx settings get --gui-next-shortcut
mx settings get --gui-prev-shortcut
mx settings get --gui-show-shortcut

# Set
mx settings set --gui-hotkey cmd+shift+m
mx settings set --gui-next-shortcut ctrl+tab
mx settings set --gui-prev-shortcut ctrl+shift+tab

# Reset to default
mx settings reset --gui-hotkey
mx settings reset --gui-next-shortcut

Additional keys: --gui-add-project-shortcut, --gui-add-workspace-shortcut, --gui-reload-shortcut, --gui-open-editor-shortcut, --gui-open-terminal-shortcut, --gui-open-finder-shortcut, --gui-open-settings-shortcut.

AI Agent Recipe

A complete example: register a project, configure it, create a workspace, and launch it.

#!/usr/bin/env bash
# Full project setup and workspace launch for an AI agent.
# Usage: ./start.sh /path/to/repo feat/my-feature
set -euo pipefail

REPO="$1"
BRANCH="$2"
NAME="${BRANCH##*/}"

# 1. Register the project
mx project add --dir "$REPO"

# 2. Set lifecycle scripts
mx project update --dir "$REPO" \
  --setup-script "npm install" \
  --stop-script "pkill -f node || true"

# 3. Define named ports (allocated per workspace so parallel runs never collide)
mx project port add --dir "$REPO" --name FRONTEND_PORT
mx project port add --dir "$REPO" --name API_PORT

# 4. Add processes (started in iTerm2 on launch)
mx project process add --dir "$REPO" --name frontend --command "PORT=$FRONTEND_PORT npm run dev"
mx project process add --dir "$REPO" --name api      --command "PORT=$API_PORT npm run api"

# 5. Add status checks (health polling while workspace runs)
mx project status-check add --dir "$REPO" \
  --name web-health --process frontend \
  --command "curl -fsS http://localhost:$FRONTEND_PORT/health" \
  --interval 10 --timeout 2 --on-fail notify

# 6. Add browser sessions (opened in Chrome on launch)
mx project browser-session add --dir "$REPO" --url "http://localhost:$FRONTEND_PORT"

# 7. Create the workspace (snapshots config, allocates ports, runs setup_script)
mx workspace create \
  --project-dir "$REPO" \
  --name "$NAME" \
  --branch "$BRANCH" \
  --target-branch main

# 8. Launch (starts processes, opens browser sessions)
# Navigate to workspace directory and launch
WORKSPACE_DIR="$HOME/muxy/workspaces/${NAME}"
cd "$WORKSPACE_DIR"
mx workspace launch

# 9. Ensure running, focus, and set tooltip in one command (agent context update)
mx workspace up --tooltip "Next.js: implementing ${BRANCH}"

# 10. Focus a specific tracked window
mx workspace focus --window 2

echo "Workspace '$NAME' is running."

Tear down when done:

cd "$WORKSPACE_DIR"
mx workspace archive

Exit Codes