cmux — tmux for GitHub Copilot CLI

Worktree lifecycle manager for parallel GitHub Copilot CLI sessions. Fork of the wonderful cmux for Claude Code

Run multiple Copilot agents in parallel on the same repo — each in its own git worktree with isolated working directory, dependencies, build artifacts, etc.

Why

Because you wanna go fast without losing your goddamn mind.

GitHub Copilot CLI works best when it has full ownership of the working directory. When you want multiple agents working on different tasks simultaneously, 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.

cmux wraps the worktree lifecycle into a single simple command and makes it effortless to manage the complete worktree lifecycle so Copilot can focus on what it does best.

Install

curl -fsSL https://raw.githubusercontent.com/alexneyler/cmux/main/install.sh | sh

Usage

cmux new <branch> — Create worktree, run setup hook, launch copilot
cmux start <branch> — Launch copilot in existing worktree
cmux cd [branch] — cd into worktree (no args = repo root)
cmux ls — List worktrees
cmux merge [branch] — Merge worktree branch into main checkout
cmux rm [branch] — Remove worktree (no args = current)
cmux init — Generate .cmux/setup hook using Copilot
cmux update — Update cmux to the latest version
cmux version — Show current version

Typical workflow

# Start a new agent on a feature branch
cmux new feature-foo

# In another terminal, start another agent
cmux new feature-bar

# List project worktrees
cmux ls

# Jump directly back into previous Copilot session
cmux start feature-foo

# cd into a worktree folder
cmux cd feature-foo
cmux cd feature-bar

# Merge worktree branch into main checkout
cmux merge feature-foo

# Or squash merge for a single clean commit
cmux merge feature-foo --squash

# Clean up worktree when done
cmux rm feature-foo

Project setup hook

When cmux new creates a worktree, it looks for an executable .cmux/setup script in the new worktree. This runs any project-specific setup — installing dependencies, symlinking secrets, generating code, etc.

Create .cmux/setup for your repo by running cmux init or creating one manually:

#!/bin/bash
REPO_ROOT="$(git rev-parse --git-common-dir | xargs dirname)"

# Symlink secrets that aren't in git
ln -sf "$REPO_ROOT/.env" .env

# Install dependencies
npm ci

Make it executable:

chmod +x .cmux/setup

See examples/ for more.

cmux init

Don't want to write the setup hook yourself? Run cmux init in your repo and Copilot will analyze the project and generate .cmux/setup for you:

cmux init
# → Analyzing repo to generate .cmux/setup...
# → Created .cmux/setup
# → Review it, then commit to your repo.

Gitignore

Add .worktrees/ to your project's .gitignore:

.worktrees/

Tab completion

cmux includes built-in tab completion for both bash and zsh. It's automatically registered when you source cmux.sh — no extra setup needed.

• cmux <TAB> — complete subcommands
• cmux start <TAB> — complete existing worktree branch names
• cmux cd <TAB> — complete existing worktree branch names
• cmux rm <TAB> — complete worktree branch names + --all

How it works

• Worktrees are created under .worktrees/<branch>/ in the repo root
• Branch names are sanitized: feature/foo becomes feature-foo
• cmux new is idempotent — if the worktree exists, it just cds there
• cmux merge with no args detects the current worktree and merges it
• cmux rm with no args detects the current worktree and removes it
• Works from anywhere inside the repo or its worktrees

License

MIT