Getting Started

Requirements

macOS, Linux, or Windows via WSL2 (see the Windows guide on GitHub — native Windows is tracked as an open TODO)
Go 1.22+ (build only — not needed at runtime)
tmux, git, make

Homebrew users on macOS / Linuxbrew users: make bootstrap will check and offer to install missing dependencies. WSL2 users: install Ubuntu, then follow the same make bootstrap flow inside the WSL shell.

Install

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

make bootstrap checks your build chain (Go / git / make / Homebrew on macOS) and offers to install anything missing, then chains into make setup.

make setup compiles ccmux, installs ccmux + ccmuxd to ~/.local/bin/, and runs the interactive wizard that checks tmux / mosh / tailscale / gh plus your AI agents — claude, codex, gemini (at least one required; npm-installed today).

Both commands 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 (Dashboard, Sessions, Projects, Notes, Claude, 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

ccmux new my-app -d "describe what you're building"

This scaffolds a project directory, runs git init, opens a tmux session named c-my-app, starts your AI agent inside it (Claude by default; switch with the agent picker in the n form or with a on an existing project), and types your description as the first prompt.

See Tutorial 1 for a full walkthrough.

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