AI工作流

🚀 Install

brew install skzv/tap/ccmux
ccmux setup

Homebrew is recommended on macOS; Linuxbrew works on Linux. ccmux setup finishes first-run setup for Tailscale, agent CLIs, and the background daemon.

Other paths:

• No Homebrew: curl -fsSL https://raw.githubusercontent.com/skzv/ccmux/main/scripts/install.sh | sh, then ccmux setup.
• From source: git clone https://github.com/skzv/ccmux.git && cd ccmux && make setup.

Works on macOS, Linux, and Windows via WSL2. Source builds require Go 1.26+.

---

⚙️ Setup is a flow, not a README.

ccmux setup is the interactive wizard. It checks tmux / mosh / tailscale / claude / gh and offers to brew install whatever's missing. The first time you launch ccmux on an unconfigured machine it offers to run setup for you (decline once and it won't ask again; set CCMUX_NO_SETUP_NUDGE=1 to always skip the prompt). For dotfiles / provisioning, ccmux setup --yes runs non-interactively — it takes the recommended answer at every prompt (install deps, generate the SSH key, install the daemon autostart) and skips the integrations that can't be scripted (Moshi pairing, Tailscale/gh browser auth). ccmux doctor is the non-interactive health check — perfect for scripting or when something stops working.

---

📱 Mobile setup

The way to use ccmux on your phone today is the Moshi app. Moshi holds a Mosh connection to your Mac alive through roaming and lid-close, raises a real push notification when an agent needs you, and shows a live picker of your sessions — tap one and you're attached to ccmux's TUI on your phone.

ccmux in the Moshi app — a live session on your phone, attached over Mosh

ccmux moshi-setup

Installs moshi-hook on the Mac, runs Easy Pair (a QR code appears in your terminal — scan it with the Moshi iOS app, done), and wires the Claude Code hooks that turn needs_input events into categorized push notifications (approval_required vs task_complete). Tap the notification, the Moshi app shows your live tmux session list, pick one, attach, answer, detach. No tokens to copy.

Plain BEL fallback works in any iOS terminal client (Blink Shell, Termius) — you lose the categories, that's it. For headless / scripted setups: ccmux moshi-setup --token <token> bypasses the QR flow.

Building your own mobile client? ccmuxd exposes an HTTP API (list / attach over a WebSocket PTY / send-keys / events / notes / usage, plus a pairing + push flow) — see the HTTP API reference.

---

🩺 Setup, doctor, update

• ccmux setup — interactive wizard, checks every dep, offers brew install for missing pieces; --yes runs it non-interactively for scripts, and the first launch on a fresh machine offers to run it for you
• ccmux doctor — non-interactive health check (great for scripting)
• ccmux update — pulls the git checkout, rebuilds, reloads ccmuxd
• ccmux uninstall — clean removal, never touches your projects or ~/.claude/

3. Working from your phone (≈3 min, one-time setup)

See the Mobile setup section above.

Uninstall

ccmux uninstall            # interactive: shows what it'll do, asks y/N
ccmux uninstall --yes      # skip the prompt
ccmux uninstall --dry-run  # preview only

What gets removed:

• Running ccmuxd (SIGTERM)
• ~/.local/bin/ccmux and ~/.local/bin/ccmuxd
• ~/.local/state/ccmux/ (socket, logs)
• ~/.local/share/ccmux/ (snapshots, daemon db)
• ~/.config/ccmux/ (unless --keep-config)
• The ccmux-styled tmux status bar on every c-* session (unless --keep-chrome)

What is never touched:

• Your project directories
• Notes under <project>/docs/
• ~/.claude/ (Claude Code state + moshi-hook entries)

To also remove moshi-hook: brew services stop moshi-hook && brew uninstall moshi-hook && brew untap rjyo/moshi.

---

📚 Tutorials

Six hands-on walkthroughs. Each is self-contained — pick whichever maps to what you're trying to do.

edit ~/.config/ccmux/config.toml: listen_tailnet = true

⚙️ Config

~/.config/ccmux/config.toml — the knobs that matter:

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

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

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

[notifications]
bell = true                          # ring local terminal BEL on needs_input

Notifications: the bell always rings on needs_input transitions when bell = true, regardless of whether moshi-hook is paired. The audible chime at your desk and the push on your phone are complementary, not duplicates. Set bell = false if you'd rather rely on phone pushes alone.

Sleep-mode notes: - safe — caffeinate -s on macOS (Apple's policy keeps it AC-only). systemd-inhibit --what=sleep:idle on Linux. - dangerous — caffeinate -d -i -m -s on macOS, works on battery too. Daemon polls battery once a minute and downgrades to safe when below low_battery_cutoff (so a forgotten laptop doesn't run flat). - very_dangerous — adds sudo -n pmset -a disablesleep 1 (macOS) / sudo -n systemctl mask sleep.target … (Linux). Requires passwordless sudo for the specific command; silently degrades to dangerous if sudo prompts. Always reverted when ccmuxd exits cleanly. Example sudoers entry (run sudo visudo -f /etc/sudoers.d/ccmux):

> # macOS
> %admin ALL=(ALL) NOPASSWD: /usr/bin/pmset -a disablesleep *
> # Linux
> %sudo ALL=(ALL) NOPASSWD: /bin/systemctl mask *, /bin/systemctl unmask *
> 

projects.root and subscription.tier are also editable inline from the Settings screen — ↑/↓ to move, Enter to edit, e to open $EDITOR for the prose-heavy fields. After editing, run ccmux update to reload the daemon with the new config.

---

🤖 Claude Code config management

• Dedicated "Claude" screen for everything in ~/.claude/
• Model picker (Opus 4.7 / Sonnet 4.6 / Haiku 4.5 / opusplan / custom) — global or per-project
• Reasoning-effort picker (low / medium / high / xhigh / max) + alwaysThinkingEnabled toggle. Writes effortLevel to ~/.claude/settings.json so every new Claude Code session inherits your default.
• Browse + create slash-command aliases, manage MCP servers, hooks, permission allowlists
• View & edit global and per-project CLAUDE.md from the TUI

4. Configure ccmux (≈2 min)

See the Config section above. ~/.config/ccmux/config.toml has the full set of knobs.

🤖 Every agent. One workflow.

Pick per project which AI runs it — ccmux works with Claude Code, Codex, Antigravity CLI, Cursor, pi, Grok, and more, speaking each one's launch and resume dialect. The choice is sticky, stored at <project>/.ccmux/agent. The dashboard, daemon state-detection, and dispatch all follow per-project. Press a in the Projects tab to switch the selected project's agent (cycles claude → codex → antigravity → cursor → pi → grok).

Dashboard rows on non-default agents get a small [codex], [antigravity], [cursor], [pi], or [grok] tag so a single glance tells you what's running where.

---

📲 Mobile workflow (Moshi / iOS / Android)

• Easy Pair via QR code — ccmux moshi-setup; scan the QR code with the Moshi app, you're paired. No token paste.
• Categorized push notifications via moshi-hook plugging into Claude Code's hooks system (approval_required, task_complete)
• In-app session picker — the Moshi app lists every tmux session on the paired host
• Auto-detection — ccmuxd suppresses its BEL trigger when moshi-hook is paired so you don't get duplicate notifications