Config Reference

Config file location: ~/.config/ccmux/config.toml

Editable inline from the Settings screen in the TUI (↑/↓ to move, Enter to edit, e to open $EDITOR).

Comment the file however you like. When ccmux saves it (a Settings row, ccmux host add, ccmux language), it rewrites only the values you changed, so your comments, blank lines and key order stay where you left them. A hand-written file still gains the default keys on its first save; your own lines don’t move. The Codex tab on the Agents screen does the same for ~/.codex/config.toml.

Interface language

lang = "ru"   # en, zh, es, ja, ko, fr, de, pt-br, ru; omit to follow LC_ALL, then LANG

lang is a top-level key: place it before any [section] headers. The TUI supports English, Simplified Chinese, Spanish, Japanese, Korean, French, German, Brazilian Portuguese, and Russian. Change the language row in Settings to switch immediately; reopening the tour and search panels uses the new language too. Most CLI output remains English. List the available languages with ccmux language, or save a preference with ccmux language ru.

[projects]

[projects]
root = "~/Projects"   # where ccmux looks for projects

[agents]

[agents]
default = "claude"   # "claude", "codex", "cursor", …; ccmux new --help lists every ID

Sets the agent used by ccmux new when no --agent flag is given. Overridden per-project by the .ccmux/agent file.

[claude]

[claude]
default_model = "claude-opus-4-8"   # or "opus" / "sonnet" / "haiku" / "opusplan" / ""

Pins a default Claude model for sessions ccmux itself launches. ccmuxd exports it as ANTHROPIC_MODEL when starting claude, so the pin survives the claude --continue || claude || zsh fallback chain (a --model flag would only apply to the first invocation). The daemon re-reads config on every launch, so a change takes effect immediately — no restart needed.

Two ways to set it without editing this file:

• TUI: open the Claude screen and press M (shift-M). The picker shows the model catalog the daemon discovered — first via claude -p (works for subscription and API users since claude handles its own auth), then via /v1/models if ANTHROPIC_API_KEY is set, falling through to a curated in-binary list. A [current] tag marks your existing pin.
• CLI: ccmux agents set-default-model <id> writes the same key. Pass no argument to clear. ccmux agents models [--refresh] [--json] lists the discovered catalog.

Empty (or unset) inherits Claude Code’s own ~/.claude/settings.json default. The pin is per-machine; sister Claude installs on shared home dirs (NFS, sshfs) keep their own settings.

[daemon]

[daemon]
poll_interval_seconds = 2
idle_seconds_for_needs_input = 3
listen_tailnet = false    # set true on a server-mode host
tailnet_port = 7474

[sleep]

[sleep]
# "off" | "safe" | "dangerous" | "very_dangerous"
mode = "safe"
low_battery_cutoff = 20   # dangerous mode auto-downgrades below this %

The default macOS mode prevents system sleep on AC power but does not override lid-close sleep. Battery behavior and system-wide overrides depend on the selected mode and platform. For unattended work, use a host that can remain powered and online.

[notifications]

[notifications]
bell = true   # ring when an agent finishes a turn and waits for input
sound = ""    # macOS: a system sound such as "Ping" or "Glass" instead of the terminal bell

The bell rings once per turn that ends in needs_input, whether or not Moshi is paired. Typing into a prompt, resizing a pane or restarting the daemon doesn’t ring it. Set bell = false to rely on phone pushes alone.

A restart (ccmux update included) also keeps which sessions you’ve already looked at and how many prompts each has had.

[subscription]

[subscription]
tier = "max5x"   # Claude plan: "pro" | "max5x" | "max20x" | "api"; omit to detect

Sizes the Claude quota bar on the dashboard. Leave it unset and ccmux shows the plan claude auth status reports. api means pay-as-you-go: token totals and estimated cost, no quota bar. Also editable from Settings.

schema_version

schema_version = 1   # top-level; written by ccmux, don't edit

ccmux writes this on every save so a later version knows how to read the file. A file without it was saved by v0.6.1 or earlier. Those versions saved tier = "api" by default, so in such a file api is read as unset and your detected plan shows again. If you really are on the API, pick it again in Settings.

[agents.muse]

[agents.muse]
command = "/path/to/muse"

Use Muse Code with ccmux

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