Summary

craigsc/cmux provides a command-line interface for managing isolated development environments for multiple Claude Code agents within a single Git repository. It addresses the challenge of parallel agent work causing conflicts and state corruption by leveraging Git worktrees, enabling developers to run agents concurrently without interference and simplifying their lifecycle management.

How It Works

The tool utilizes Git worktrees, where each agent operates in its own distinct directory tree that shares the same .git repository. This approach offers true isolation without the overhead of cloning or syncing, ensuring branches remain synchronized and preventing edit conflicts. cmux abstracts the complexity of managing these worktrees, providing simple commands to create, switch between, merge, and remove agent environments.

Quick Start & Requirements

Installation is straightforward via a shell script: curl -fsSL https://github.com/craigsc/cmux/releases/latest/download/install.sh | sh. Users should add .worktrees/ to their .gitignore. The primary command to start a new agent environment is cmux new <your feature name>. Prerequisites include Git and the Claude CLI. A .cmux/setup hook can automate project-specific initialization tasks.

Highlighted Details

• Git Worktree Orchestration: Manages the full lifecycle of agent worktrees, including creation (new), resuming (start), switching (cd), listing (ls), merging (merge), and removal (rm).
• Automated Setup Hooks: Supports a .cmux/setup script for project-specific initialization (e.g., dependency installation, symlinking secrets), which can be auto-generated using Claude via cmux init.
• Tab Completion: Offers built-in shell completion for bash and zsh, simplifying command usage and branch selection.
• Bash Implementation: Written purely in Bash, relying only on git and the Claude CLI for dependencies.

Maintenance & Community

The provided README does not contain specific details regarding maintainers, community channels (like Discord or Slack), sponsorships, or a public roadmap.

Licensing & Compatibility

The project is released under the MIT license, which is permissive and generally compatible with commercial use and integration into closed-source projects.

Limitations & Caveats

Operation is dependent on the presence and correct functioning of the Claude CLI. The tool's effectiveness relies on the underlying Git worktree implementation. No specific limitations regarding platform support or known bugs are detailed in the README.