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 recommended path is Homebrew — one command, deps come along for the ride:

brew install skzv/tap/ccmux
ccmux setup

brew install pulls cross-compiled binaries from the GitHub Release and wires tmux, mosh, and ripgrep. ccmux setup runs the interactive wizard for the pieces brew can’t cover — Tailscale, the AI agent CLIs (claude / codex / agy), and the ccmuxd background service.

Alternative: one-line install script (no Homebrew)

curl -fsSL https://raw.githubusercontent.com/skzv/ccmux/main/scripts/install.sh | sh
ccmux setup

Downloads the latest release tarball to ~/.local/bin/ and strips the macOS quarantine attribute automatically.

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.