muse worktree — multiple simultaneous branch checkouts

A worktree is a second (or third, or hundredth) checked-out working directory linked to the same .muse/ object store. Each worktree has its own branch and its own state/ directory — multiple agents (or engineers) can work on different branches simultaneously with zero interference.

Mental model

myproject/                    ← main worktree
  state/                      ← main branch files
  .muse/                      ← shared object store, commits, refs

myproject-feat-audio/         ← linked worktree
  state/                      ← feat/audio files (populated at creation)

myproject-hotfix-001/         ← another linked worktree
  state/                      ← hotfix/001 files

All worktrees share one .muse/ store. A commit made in myproject-feat-audio/ is immediately visible (by commit ID) to the main worktree and all other linked worktrees.

Subcommands

muse worktree add <name> <branch>

Create a new linked worktree checked out at <branch>.

muse worktree add feat-audio feat/audio
muse worktree add hotfix-001 hotfix/001

The worktree directory is created as a sibling of the repository root, named <repo>-<name>. Its state/ is pre-populated from the branch's latest snapshot.

Constraints:

• <name> is validated like a branch name (no path separators, no control characters).
• <branch> must already exist.
• A worktree with the same <name> must not already exist.

muse worktree list

List all worktrees (main + linked).

  name                     branch                          HEAD          path
──────────────────────────────────────────────────────────────────────────────────
* (main)                   main                            cccccccc0000  /Users/me/myproject
  feat-audio               feat/audio                      a1b2c3d4ef56  /Users/me/myproject-feat-audio
  hotfix-001               hotfix/001                      deadbeef0012  /Users/me/myproject-hotfix-001

The * marks the main worktree.

muse worktree remove <name>

Remove a linked worktree and its state/ directory.

muse worktree remove feat-audio
muse worktree remove feat-audio --force   # skip confirmation

The branch itself is not deleted — only the worktree directory and its metadata entry are removed.

muse worktree prune

Remove metadata entries for worktrees whose directories no longer exist (e.g. manually deleted).

muse worktree prune

Agent workflows

Parallel agent tasks

# Each agent works in its own worktree on its own branch:
muse worktree add agent-001 feat/agent-001
muse worktree add agent-002 feat/agent-002
muse worktree add agent-003 feat/agent-003

# Agents run independently in:
#   myproject-agent-001/state/
#   myproject-agent-002/state/
#   myproject-agent-003/state/

Simultaneous hotfix + feature

# Keep working on the feature in the main worktree
# while fixing the hotfix in a linked worktree:
muse worktree add hotfix hotfix/critical-bug
cd ../myproject-hotfix
muse commit -m "fix: patch the critical bug"
muse push
cd ../myproject
# Continue on main branch, uninterrupted

Worktree HEAD tracking

Each linked worktree has its own HEAD file stored at .muse/worktrees/<name>.HEAD. This is independent of the main worktree's .muse/HEAD, allowing each worktree to be on a different branch simultaneously.

Exit codes