Getting Started

Requirements

macOS, Linux, or Windows via WSL2 (see the Windows guide on GitHub — native Windows is tracked as an open TODO)
One of: Homebrew (macOS / Linuxbrew), curl + a POSIX shell, or Go 1.26+ for the from-source path
tmux, git (installed automatically by Homebrew / the install script / make bootstrap)

Install

The shortest path is the install script — one command, no tap to add:

curl -fsSL https://ccmux.ai/install | sh
ccmux setup

It downloads the latest release tarball to ~/.local/bin/ and strips the macOS quarantine attribute for you. https://ccmux.ai/install serves scripts/install.sh from the repo verbatim — read it first if you’d rather not pipe a URL into a shell, or curl the raw GitHub copy directly. ccmux setup then runs the interactive wizard for the pieces a download can’t cover — Tailscale, the AI agent CLIs (claude / codex / agy), and the ccmuxd background service.

Homebrew

brew trust --tap skzv/tap
brew install skzv/tap/ccmux
ccmux setup

Homebrew 6 refuses formulae from third-party taps until you vouch for the tap, so brew trust comes first — without it the install stops with Refusing to load formula skzv/tap/ccmux from untrusted tap skzv/tap. You only do it once per machine. (The tap is skzv/tap, not skzv/homebrew-tap — Homebrew drops the prefix.)

brew install pulls the same cross-compiled binaries from the GitHub Release and wires up tmux, mosh, and ripgrep as dependencies.

Alternative: from source

mkdir -p ~/Projects && cd ~/Projects
git clone https://github.com/skzv/ccmux.git
cd ccmux && make bootstrap

make bootstrap checks your build chain and offers to install anything missing, then chains into make setup. Use this if you want to track main or hack on ccmux itself.

All three paths are idempotent — safe to re-run at any time.

First run

ccmux

The TUI launches with a first-run tour. Press ? on any screen for the full keymap.

Key bindings

Key	Action
`1`–`7`	Switch screens (Home, Conversations, Projects, Notes, Agents, Settings, Network)
`Enter`	Attach to selected session
`?`	Contextual help
`T`	Re-run first-run tour
`j` / `k` or `↑` / `↓`	Navigate lists
`x`	Kill selected session

Your first project

In the TUI: press 3 for Projects, then n to open the new-project form. Fill in the name, pick an agent (Claude / Codex / Antigravity / Cursor / pi / Grok), and press Enter. ccmux creates the directory under projects.root and starts the agent session immediately.

From the shell:

ccmux new my-app

Creates the directory and boots the session with your default agent. The TUI opens automatically on the Home screen where you can attach with Enter.

See Tutorial 1 for a full walkthrough.

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