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

[projects]

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

[agents]

[agents]
default = "claude"   # "claude" | "codex" | "antigravity" | "cursor" | "pi" | "grok"

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]
# "safe" | "dangerous" | "very_dangerous"
mode = "safe"
idle_release_minutes = 10
low_battery_cutoff = 20   # dangerous mode auto-downgrades below this %

Mode	Behaviour
`safe`	`caffeinate -s` (AC only) on macOS; `systemd-inhibit` on Linux
`dangerous`	Works on battery; auto-downgrades when battery < `low_battery_cutoff`
`very_dangerous`	Lid-close override via `pmset`/`systemctl`; requires passwordless sudo

[notifications]

[notifications]
bell = true                    # terminal BEL on needs_input
moshi_suppresses_bell = false  # mute bell when moshi-hook is also reporting

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