by craigsc
cmux: tmux for Claude Code
# Add to your Claude Code skills
git clone https://github.com/craigsc/cmuxRun a fleet of Claude agents on the same repo — each in its own worktree, zero conflicts, one command each.
Claude Code works best when it has full ownership of the working directory. Want two agents working in parallel? They'll stomp on each other — conflicting edits, dirty state, broken builds. You need separate checkouts.
Git worktrees are the perfect primitive for this. They share the same .git database but give each agent its own directory tree — no cloning, no syncing, branches stay in lockstep. cmux wraps the entire worktree lifecycle into single commands so you can spin agents up, jump between them, and tear them down without thinking about it.
You wanna go fast without losing your goddamn mind. This is how.
curl -fsSL https://github.com/craigsc/cmux/releases/latest/download/install.sh | sh
Then add .worktrees/ to your .gitignore:
echo '.worktrees/' >> .gitignore
cmux new <your feature name> # creates worktree + branch, runs setup hook, opens Claude
That's it. One command, one agent, fully isolated. See Workflow for the full loop.
| Command | What it does |
|---------|-------------|
| cmux new <branch> | Create new worktree + branch, run setup hook, launch Claude |
| cmux start <branch> | Continue where you left off in an existing worktree |
| cmux cd [branch] | cd into a worktree (no args = repo root) |
| cmux ls | List active worktrees |
| | Merge worktree branch into your primary checkout (no args = current worktree) |
| | Remove a worktree and its branch (no args = current, = every worktree with confirmation) |
| | Generate hook using Claude ( to regenerate) |
| | Update cmux to the latest version |
| | Show current version |
No comments yet. Be the first to share your thoughts!
cmux merge [branch] [--squash]cmux rm [branch \| --all]--allcmux init [--replace].cmux/setup--replacecmux updatecmux versionYou're building a feature:
cmux new feature-auth # agent starts working on auth
Bug comes in. No problem — spin up another agent without leaving the first one:
cmux new fix-payments # second agent, isolated worktree, independent session
Merge the bugfix when it's done:
cmux merge fix-payments --squash
cmux rm fix-payments
Come back tomorrow and pick up the feature work right where you left off:
cmux start feature-auth # picks up right where you left off
The key distinction: new = new worktree, new session. start = existing worktree, continuing session.
When cmux new creates a worktree, it runs .cmux/setup if one exists. This handles project-specific init — symlinking secrets, installing deps, running codegen. If no setup hook exists, you'll be prompted to generate one.
The easy way — let Claude write it for you:
cmux init
Or create one manually:
#!/bin/bash
REPO_ROOT="$(git rev-parse --git-common-dir | xargs dirname)"
ln -sf "$REPO_ROOT/.env" .env
npm ci
See examples/ for more.
.worktrees/<branch>/ in the repo rootfeature/foo becomes feature-foocmux new is idempotent on the worktree — if it already exists, it skips creation and setup, but still launches a new Claude sessioncmux merge and cmux rm with no args detect the current worktree from $PWDYou never have to remember branch names. Built-in completion for bash and zsh — automatically registered when you source cmux.sh, no extra setup.
cmux <TAB> — subcommandscmux start <TAB> — existing worktree branchescmux cd <TAB> — existing worktree branchescmux rm <TAB> — worktree branches + --allcmux merge <TAB> — worktree branchescmux init <TAB> — --replaceMIT