CLI Reference

Use the CLI to create projects, attach to sessions, and maintain your installation from a shell or script. Run a command with --help to see its available flags.

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. Without --agent, ccmux uses [agents] default from config.toml, else Claude. Pick another agent with --agent codex, --agent cursor and so on; ccmux new --help lists every agent ID. The choice is stored at <project>/.ccmux/agent and picked up by future sessions.

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

Run from a script or a pipe, new, shell and resume still start the session, then print ccmux attach <name> instead of attaching.

ccmux list

ccmux list [--json] [--host <name>] [--filter <text>]

Print the sessions on this machine, every agent’s plus plain shells, with the state ccmuxd classified them in. If the daemon isn’t running, the list comes straight from tmux and every state is unknown.

With --host, you get that host’s sessions as its ccmuxd classified them, with the host’s name in the HOST column.

--filter <text> (-f) lists only the sessions whose name or project contains the text, or whose host or agent starts with it. Case doesn’t matter. The TUI’s session filter matches the same way.

ccmux attach

ccmux attach [session|project|path] [--host <name>]

Attach to a running session by the name ccmux list prints, or to a project’s session by project name, starting it if it isn’t running. An argument with a / is a path; no argument means the current directory. A directory that doesn’t exist is an error.

A project’s session is found by its directory. Two projects with the same folder name, like ~/Projects/api and ~/work/api, get separate sessions: whichever started first keeps c-api, and the other gets a name like c-api-iwyjf, where the five letters come from its full path. Nothing gets renamed, and attach, new and kill never land on the other project’s session.

With --host, the argument is a running session on that host, or a project name or absolute path there. The host’s ccmuxd starts the project’s session if it isn’t running. ccmux then attaches over mosh, or ssh for a host added with --mosh=false, with the host’s user and ssh port. Without a terminal it prints the ccmux attach --host command to run instead.

In the TUI, press Enter on a remote row. ccmux runs ssh -t, or mosh for a host pinned with ccmux host add.

ccmux kill / rename

ccmux kill <project|session> [--host <name>]
ccmux rename <old-name> <new-name> [--host <name>]

kill takes a session name or a project name and prints what it killed. For a project it kills that project’s own session. If the project has none but a same-named one elsewhere holds c-api, the error says where that one runs and gives you the ccmux kill c-api to run. A new name for rename can use letters, digits, - and _, and can’t start with -. Both refuse a name that starts with $, because tmux reads $1 as a session ID and would act on whichever session has it.

With --host, the host’s ccmuxd does the kill or rename. kill --host takes a session name, a project name, or an absolute path on that host; a relative path would be a directory on this machine, so it’s refused. A missing session, a name that’s taken and a daemon that doesn’t answer each get their own message:

$ ccmux kill --host mini api
killed c-api on mini
$ ccmux rename --host mini scratch api
mini already has a session named "api"
$ ccmux kill --host mini scratch
can't reach ccmuxd on mini (mini.tail-xxxxx.ts.net:7474): connect: connection refused

ccmux shell

ccmux shell [--agent <id>|shell] [--name <name>] [--path <dir>] [--host <name>]

Start a session that isn’t tied to a project, here or on a host you added with ccmux host add. --agent shell gives you a plain $SHELL. --path defaults to sessions.default_dir, else $HOME on the host that runs the session. With --host, ccmux attaches over ssh.

ccmux list-conversations

ccmux list-conversations [--query <text>] [--since 7d] [--limit <n>] [--json] [--include-headless]

Past conversations from every supported agent, newest first, including ones started outside ccmux. --since takes a Go duration or days: 24h, 7d, 1d12h. Headless runs (claude -p, codex exec) are hidden unless you pass --include-headless.

ccmux resume / delete-conversation

ccmux resume [<id>] [--agent <id>]
ccmux delete-conversation <id> [--force]

resume starts the conversation’s agent with its own resume flag in a new tmux session. With no ID it picks the most recent conversation, or the most recent for one agent with --agent. delete-conversation removes the transcript for good and asks first unless you pass --force.

Both take the shortened ID from the list-conversations table as is, trailing … included, or any unique prefix. A prefix that matches more than one conversation lists the matches.

ccmux update

ccmux update [--dry-run] [--skip-pull] [--no-restart] [--setup | --no-setup-prompt] [--repo <path>]

Update a Homebrew installation through brew, or pull and rebuild a source checkout, then restart the daemon. For download-script installations, rerun the installer. See the maintenance guide.

After a successful update ccmux offers to rerun ccmux setup, so you can go through options the new version added. --setup runs it without asking, and --no-setup-prompt skips it. --repo points at your git checkout and takes the source path even on a Homebrew install; without it ccmux finds the checkout the running binary came from, else ~/Projects/ccmux.

ccmux daemon

ccmux daemon install   # register ccmuxd under launchd / systemd
ccmux daemon start
ccmux daemon stop
ccmux daemon restart   # pick up a newly installed binary
ccmux daemon status
ccmuxd --version       # print the daemon binary's version

ccmux host add

ccmux host add <name> <address> [--user <user>] [--port 7474] [--ssh-port 22] [--mosh=false]
ccmux host remove <name>
ccmux host list

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

<address> is a tailnet name or IP, optionally as user@host. Ports go in the flags, not the address: --port is the remote ccmuxd port, --ssh-port its sshd port. Pinned hosts attach with mosh; --mosh=false keeps them on plain ssh. The name must start with a letter or digit, and local is reserved for this machine.

The name is what --host takes in list, attach, kill, rename, shell and notes. For a host entry with no port, say one you wrote into config.toml by hand, they use this machine’s daemon.tailnet_port, else 7474, the same as the TUI.

ccmux notes

ccmux notes list <project> [--host <name>]
ccmux notes read <project> <file> [--host <name>]
ccmux notes search <project> <query> [--host <name>]

The Notes screen from a shell. list prints every markdown file in the project, read prints one (the path is relative to the project), and search looks for literal text, ignoring case. --host reads a pinned host’s notes over the tailnet. The commands go through ccmuxd, so the daemon has to be running.

ccmux project

ccmux project <name>

What Enter on a project shows in the TUI: its running sessions, then its past conversations with the IDs ccmux resume takes. With nothing running, it points you at ccmux attach <name>.

ccmux pair

ccmux pair

Print a QR code for a mobile client to scan. The client redeems the one-time token with POST /v1/pair: ccmuxd adds the phone’s SSH key to ~/.ssh/authorized_keys, and can register it for push notifications in the same step. The token expires in 5 minutes. ccmuxd has to be running with daemon.listen_tailnet = true.

ccmux mcp

ccmux mcp register [--allow-mutate] [--force]
ccmux mcp status
ccmux mcp unregister

Register ccmux-mcp with Claude Code as a user-scope MCP server. register won’t replace a ccmux entry that runs something other than ccmux-mcp unless you pass --force. ccmux uninstall runs unregister for you. See the MCP server guide.

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

ccmux setup [--yes]

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

Safe to rerun. --yes (-y) runs it without prompts, for dotfiles and provisioning scripts: every question takes the recommended answer (install missing dependencies, generate the SSH key, install the ccmuxd service), and the steps that need you, Moshi pairing and the Tailscale or gh sign-in, are reported and skipped.

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/.

If you registered the MCP server, uninstall also removes its entry from ~/.claude.json, after a backup.

ccmux language

ccmux language          # list supported languages
ccmux language ru       # save Russian as the interface language
ccmux language pt-BR    # save Brazilian Portuguese

Reopen ccmux after changing the preference from the shell. To switch an open TUI immediately, use the language row in Settings.

ccmux contribute

ccmux contribute

Show links for reporting issues, improving translations, and submitting pull requests. The same prompt is available in the TUI help panel.

ccmux usage

ccmux usage [--json]

Show recorded usage from the local daemon. Muse token counts include child agents and exclude duplicate records; unavailable cost is labeled explicitly.

Under the table it prints Claude’s current 5-hour block, the one the dashboard’s quota bar counts, and when it resets:

CLAUDE 5-HOUR BLOCK  started 13:00, resets 18:00 (in 3h05m)
PROMPTS  MESSAGES  INPUT  OUTPUT  CACHE WRITE  CACHE READ  EST. COST
6        14        7200   2100    24000        540000      $0.31

--json carries it as claude_block. See GET /v1/usage for the fields.

Use Muse Code with ccmux

Help improve ccmux

Found a bug, an unclear guide, or a translation that could read better? Contributions of any size are welcome. Open an issue or send a pull request.

Contribute to ccmux Improve the website or translations

Spotted an error or something out of date? Open an issue on GitHub.