Local Workspaces

Local workspaces use git worktrees on your local machine. Worktrees share the .git directory with your main repository while maintaining independent working changes and checkout state.

How Worktrees Work

A worktree is a separate directory on the same filesystem as the main repository that shares a .git but has independent working changes and checkout state. All committed changes from any worktree are visible to all other worktrees including the main repository.

It's important to note that a worktree is not locked to a branch. The agent can switch to new branches, enter a detached HEAD state, etc. When you create a workspace, the agent will begin at the selected branch but may switch freely in the course of the session. We empower users to define their agent's branching strategy in AGENTS.md

Filesystem Layout

Local workspaces are stored in ~/.cmux/src/<project-name>/<workspace-name>.

Example layout:

~/.cmux/src/
  cmux-main/
    improved-auth-ux/
    fix-ci-flakes/