cmux: git worktrees as the unit of isolation for Claude Code agents

The problem cmux solves: two agents, one working directory

Claude Code assumes it owns the directory it runs in. The README states this directly: "Claude Code works best when it has full ownership of the working directory." Run a second agent in the same checkout and you get conflicting edits, dirty state and broken builds, because both processes read and write the same files and the same index.

The obvious fix is to clone the repository again. That costs disk, duplicates the object database, and leaves you syncing branches between copies by hand. cmux takes the other primitive: git worktrees. A worktree shares the same .git database as the primary checkout but gets its own directory tree, so branches stay in lockstep and nothing is cloned. The README calls worktrees "the perfect primitive for this" and describes cmux as wrapping the whole worktree lifecycle into single commands.

The audience is narrow and specific. If you run one Claude Code session at a time, cmux adds nothing you cannot do with git worktree directly. It earns its place when you want a second agent on a bugfix while the first is still mid-feature, and you do not want to think about directory layout, branch naming or cleanup.

How cmux maps branches to directories

The layout is fixed. Worktrees live under .worktrees/<branch>/ in the repository root, which is why the install instructions append .worktrees/ to .gitignore. Branch names are sanitized for the filesystem: the README gives the example that feature/foo becomes feature-foo. That means the directory name and the branch name can diverge, and anything you script against the path needs to account for the substitution.

Base branch detection follows a fixed order: remote HEAD first, then main, then master. If your default branch is named something else and the remote HEAD is not set, cmux will fall through to main or master, which may be wrong. The --from flag exists for that case and for branching off a feature branch instead of the default.

Two behaviours are worth knowing before you build a habit around them. First, cmux new is idempotent on the worktree: if the directory already exists, cmux skips creation and the setup hook but still launches a new Claude session. Second, cmux merge and cmux rm with no arguments detect the current worktree from $PWD, so running them from the wrong directory targets the wrong branch. The README does not document rollback for merge or rm, so treat both as operations to run deliberately.

The implementation is pure bash and depends only on git and the Claude CLI. There is no daemon, no state file beyond the worktrees themselves, and no background process to supervise.

Installing cmux and running your first agent

The install path is a shell script served from the latest GitHub release. The README gives it as a single curl piped to sh.

curl -fsSL https://github.com/craigsc/cmux/releases/latest/download/install.sh | sh

After that, exclude the worktree directory from git so the agents' checkouts never show up as untracked files in your primary checkout.

echo '.worktrees/' >> .gitignore

You need a project-specific setup hook if the checkout has to do more than exist. cmux runs .cmux/setup when it creates a worktree, and if no hook is present it prompts you to generate one. cmux init asks Claude to write that hook; --replace regenerates it. A manual hook is a bash script that runs inside the new worktree. The README's own example symlinks a secrets file from the shared repository root and installs dependencies.

#!/bin/bash
REPO_ROOT="$(git rev-parse --git-common-dir | xargs dirname)"
ln -sf "$REPO_ROOT/.env" .env
npm ci

With that in place, the first real use is one command. It creates the worktree and branch, runs the setup hook, and opens Claude.

cmux new feature-auth

What you should see is a new directory at .worktrees/feature-auth, a matching branch, and a Claude session running inside it. A second agent on an unrelated task is the same command with a different name, and the README's workflow shows merging the finished one with cmux merge fix-payments --squash followed by cmux rm fix-payments. To resume an existing worktree the next day, use cmux start feature-auth rather than new; the README draws the distinction as new meaning a new worktree and session, start meaning an existing worktree and a continuing session.

The setup hook is where cmux projects actually break

Worktree creation is the easy part. The hard part is that a fresh worktree is a bare checkout: no node_modules, no .env, no generated code, no local database. Everything your build needs that is not committed has to be recreated, and .cmux/setup is the only place cmux gives you to do it.

This is a real failure mode, not a theoretical one. If the hook is missing or incomplete, cmux new still succeeds, Claude still launches, and the agent starts working in a directory where the test command fails or the dev server will not start. The README acknowledges the scope by listing what hooks handle: "symlinking secrets, installing deps, running codegen." Each of those is a thing the hook author has to get right per repository, and cmux cannot verify it.

The example hook in the README symlinks .env from the repository root using git rev-parse --git-common-dir. That works for a single secrets file. It does not cover local databases with per-worktree state, ports that collide when two dev servers run at once, or Docker volumes keyed by directory name. The README is silent on all three. The examples/ directory contains a setup-node example, so there is at least one reference beyond the inline snippet, but the README does not enumerate what it covers.

There is also a cost question the README does not answer: npm ci in a hook means every cmux new pays a full dependency install. For a large project, spinning up an agent is no longer instantaneous.

Where cmux is the wrong tool

cmux is a local, single-machine convenience layer. The README documents no SSH support, no remote host targeting and no way to run worktrees on another machine, so anyone searching for cmux ssh will not find it in the documentation. If your agents need to run on a build server or a shared remote box, cmux as described does not reach there.

It is also not an orchestrator. There is no scheduling, no dependency graph between agents, no monitoring of what another session is doing, and no automatic rebase or conflict resolution. The README points to a separate community project, claude-orchestration-in-cmux, for exactly that: a Claude Code skill that "discovers panes, delegates tasks to other Claude sessions, monitors progress via screen polling, and manages the full commit-merge-rebase cycle with worktree isolation." That is a different tool built on top, and it is a signal about where cmux stops.

Finally, cmux is a wrapper around git and the Claude CLI. If you already have a worktree script you like, or you use a different agent CLI, cmux's value drops to tab completion and a consistent .worktrees/ layout. That is not nothing, but it is not a reason to migrate.

How cmux differs from tmux, Warp and Ghostty

The name invites the comparison, so it is worth being precise. tmux is a terminal multiplexer: it manages panes and windows inside one terminal, and every pane shares the same working directory unless you cd. cmux does not multiplex terminals at all. It manages directories, one git worktree per agent, and the isolation is at the filesystem and git level rather than the display level. You can run cmux inside tmux, and the two solve different problems.

Warp and Ghostty are terminal emulators. They change how you type commands and render output; they do not create checkouts, branches or setup hooks. A terminal emulator will happily let two agents share one directory, which is the exact situation cmux exists to prevent. Choosing between them is not a real choice, because they sit at different layers of the stack.

The closer alternative is plain git worktree plus a shell alias. git worktree add .worktrees/feature-auth -b feature-auth gives you the isolated directory; what it does not give you is the setup hook, the branch-name sanitization, the merge and rm subcommands that infer the current worktree, or the bash and zsh completion that the README describes for cmux subcommands and branch names. If your team already has those in a Makefile, cmux is redundant. If not, it is roughly a hundred lines of bash you would otherwise write badly.

Maintenance, licence and what upgrading costs

The repository is not archived, and the last push was on 2026-06-16. Releases are tagged: v0.1.2 and v0.1.3 both landed on 2026-02-15 and 2026-02-16, and v0.1.4 followed on 2026-04-20. The version series is still in 0.1.x, which is worth reading as a statement about API stability rather than as a criticism.

Upgrades have a documented path: cmux update updates to the latest version, and cmux version reports what you are running. Because the install is a shell script from the releases page rather than a package manager, there is no lockfile pinning a version and no dependency tree to audit. That cuts both ways: nothing to break transitively, and nothing to hold you at a known-good release except your own copy of cmux.sh.

The licence is MIT, stated in the README and present as a LICENSE file at the repository root. MIT permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive arrangement with few obligations, but the usual caveat applies: if you vendor cmux.sh into a product, keep the notice, and if your organisation has a policy on copyleft or attribution, have someone who can give legal advice read the LICENSE file rather than this paragraph.

Editorial conclusion

Adopt cmux if you already run Claude Code against a single repository and have hit the point where two agents edit the same files. Skip it if you need a scheduler, remote execution or a Windows-native tool: the README documents a pure bash implementation, git worktrees under .worktrees/, and nothing about SSH, remote hosts or a GUI. Before relying on it, check that your .gitignore excludes .worktrees/, that your project can build inside a fresh checkout, and read cmux.sh to confirm the merge and rm behaviour matches how you want branches handled, since the README does not document rollback for either command.

Frequently asked questions

Official sources

1. craigsc/cmux on GitHub
2. Issues
3. License: MIT
4. README
5. Releases