CLI Reference

All subcommands are also accessible from within the TUI. The CLI surface exists for scripts, muscle memory, and pipelines.

ccmux

ccmux [path]

Launch the TUI. Optional path scopes the session to that directory instead of projects.root.

ccmux new

ccmux new <name> [--agent <id>]

Create a new project directory under projects.root and start an agent session. The agent defaults to Claude; override per-project with --agent codex, --agent antigravity, --agent cursor, --agent pi, or --agent grok, or set [agents] default in config.toml. The choice is stored at <project>/.ccmux/agent and picked up by future sessions.

In the TUI, press 3 (Projects) → n to fill in the name and agent interactively.

ccmux list

ccmux list

Print all running sessions (local + any discovered remote hosts) with their state.

ccmux attach

ccmux attach <name>

Attach to a named session. Uses ssh -t for remote sessions; mosh if the host was pinned with --mosh.

ccmux update

ccmux update [--dry-run] [--skip-pull] [--no-restart]

Pull the git checkout, rebuild, reinstall, and reload ccmuxd.

ccmux daemon

ccmux daemon install   # register ccmuxd under launchd / systemd
ccmux daemon start
ccmux daemon stop
ccmux daemon status

ccmux host add

ccmux host add <name> --addr <host:port> [--mosh]

Manually pin a host (for non-Tailscale hosts or to force a specific port). Auto-discovered Tailscale peers don’t need this.

ccmux moshi-setup

ccmux moshi-setup [--token <token>]

Install moshi-hook, run Easy Pair (QR code), wire Claude Code hooks. --token bypasses the QR flow for headless setups.

ccmux setup

Interactive wizard — checks all dependencies, offers to install missing ones.

ccmux doctor

ccmux doctor

Non-interactive health check. Include the output when filing bug reports.

ccmux agents

ccmux agents models [--refresh] [--json]
ccmux agents set-default-model [model-id]

Configure agent-level settings ccmux applies when launching sessions.

• models lists the Claude model catalog the daemon has discovered, tagged with the source (claude-cli / api / fallback) and a * next to your current pin. --refresh forces a synchronous re-fetch from the daemon (otherwise the cached snapshot is returned). --json emits the raw catalog — same shape as /v1/models.

• set-default-model pins the model ccmux passes as ANTHROPIC_MODEL on every Claude session it launches. Accepts an alias (opus / sonnet / haiku / opusplan) for auto-tracking Anthropic’s current bindings, or a concrete ID (claude-opus-4-8) to pin a specific version. Omit the argument to clear. Writes [claude] default_model in ~/.config/ccmux/config.toml; the daemon picks it up on the next session launch — no restart needed.

The discovery chain works for subscription and API users: ccmuxd calls claude -p first (which handles its own auth), falls back to /v1/models if ANTHROPIC_API_KEY is set, then to a curated in-binary list. Refreshes weekly.

ccmux uninstall

ccmux uninstall [--yes] [--dry-run] [--keep-config] [--keep-chrome]

Clean removal. Never touches project directories, notes, or ~/.claude/.

Spotted an error or something out of date? Edit this page on GitHub.