Getting Started

Install ccmux on the machine that will run your agents. After setup, create a project and attach to its first session.

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 and git. Homebrew installs the runtime dependencies; the download script installs ccmux binaries only. Run ccmux setup to check dependencies, or use make bootstrap when building from source.

Install

Choose the download script or Homebrew. Use the source build if you want to develop ccmux itself.

Download script

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

The script installs the latest release binaries in ~/.local/bin/. Add that directory to your shell’s PATH if the installer prompts you. You can inspect the install script before running it.

The setup wizard checks dependencies, helps configure your agent CLIs, and installs the background daemon. Sign in to your chosen agent before starting a session. For remote access, connect your devices to Tailscale as well.

Homebrew

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

Trust the tap once per machine. Homebrew installs ccmux and its packaged dependencies, including tmux, Mosh, and ripgrep.

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.

You can rerun the setup wizard later to review your configuration.

First run

ccmux

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

Key bindings

Your first project

In the TUI: press 2 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.

Next steps

• Manage multiple sessions and detach without stopping an agent.
• Connect from your phone or add another machine.
• Connect an MCP client to inspect sessions from your agent.
• If setup fails, run ccmux doctor and follow the maintenance guide.

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