worktree.md
markdown
| 1 | # `muse worktree` — multiple simultaneous branch checkouts |
| 2 | |
| 3 | 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. |
| 4 | |
| 5 | ## Mental model |
| 6 | |
| 7 | ``` |
| 8 | myproject/ ← main worktree |
| 9 | state/ ← main branch files |
| 10 | .muse/ ← shared object store, commits, refs |
| 11 | |
| 12 | myproject-feat-audio/ ← linked worktree |
| 13 | state/ ← feat/audio files (populated at creation) |
| 14 | |
| 15 | myproject-hotfix-001/ ← another linked worktree |
| 16 | state/ ← hotfix/001 files |
| 17 | ``` |
| 18 | |
| 19 | 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. |
| 20 | |
| 21 | ## Subcommands |
| 22 | |
| 23 | ### `muse worktree add <name> <branch>` |
| 24 | |
| 25 | Create a new linked worktree checked out at `<branch>`. |
| 26 | |
| 27 | ```bash |
| 28 | muse worktree add feat-audio feat/audio |
| 29 | muse worktree add hotfix-001 hotfix/001 |
| 30 | ``` |
| 31 | |
| 32 | 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. |
| 33 | |
| 34 | **Constraints:** |
| 35 | - `<name>` is validated like a branch name (no path separators, no control characters). |
| 36 | - `<branch>` must already exist. |
| 37 | - A worktree with the same `<name>` must not already exist. |
| 38 | |
| 39 | ### `muse worktree list` |
| 40 | |
| 41 | List all worktrees (main + linked). |
| 42 | |
| 43 | ``` |
| 44 | name branch HEAD path |
| 45 | ────────────────────────────────────────────────────────────────────────────────── |
| 46 | * (main) main cccccccc0000 /Users/me/myproject |
| 47 | feat-audio feat/audio a1b2c3d4ef56 /Users/me/myproject-feat-audio |
| 48 | hotfix-001 hotfix/001 deadbeef0012 /Users/me/myproject-hotfix-001 |
| 49 | ``` |
| 50 | |
| 51 | The `*` marks the main worktree. |
| 52 | |
| 53 | ### `muse worktree remove <name>` |
| 54 | |
| 55 | Remove a linked worktree and its `state/` directory. |
| 56 | |
| 57 | ```bash |
| 58 | muse worktree remove feat-audio |
| 59 | muse worktree remove feat-audio --force # skip confirmation |
| 60 | ``` |
| 61 | |
| 62 | The branch itself is **not** deleted — only the worktree directory and its metadata entry are removed. |
| 63 | |
| 64 | ### `muse worktree prune` |
| 65 | |
| 66 | Remove metadata entries for worktrees whose directories no longer exist (e.g. manually deleted). |
| 67 | |
| 68 | ```bash |
| 69 | muse worktree prune |
| 70 | ``` |
| 71 | |
| 72 | ## Agent workflows |
| 73 | |
| 74 | ### Parallel agent tasks |
| 75 | |
| 76 | ```bash |
| 77 | # Each agent works in its own worktree on its own branch: |
| 78 | muse worktree add agent-001 feat/agent-001 |
| 79 | muse worktree add agent-002 feat/agent-002 |
| 80 | muse worktree add agent-003 feat/agent-003 |
| 81 | |
| 82 | # Agents run independently in: |
| 83 | # myproject-agent-001/state/ |
| 84 | # myproject-agent-002/state/ |
| 85 | # myproject-agent-003/state/ |
| 86 | ``` |
| 87 | |
| 88 | ### Simultaneous hotfix + feature |
| 89 | |
| 90 | ```bash |
| 91 | # Keep working on the feature in the main worktree |
| 92 | # while fixing the hotfix in a linked worktree: |
| 93 | muse worktree add hotfix hotfix/critical-bug |
| 94 | cd ../myproject-hotfix |
| 95 | muse commit -m "fix: patch the critical bug" |
| 96 | muse push |
| 97 | cd ../myproject |
| 98 | # Continue on main branch, uninterrupted |
| 99 | ``` |
| 100 | |
| 101 | ## Worktree HEAD tracking |
| 102 | |
| 103 | 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. |
| 104 | |
| 105 | ## Exit codes |
| 106 | |
| 107 | | Code | Meaning | |
| 108 | |------|---------| |
| 109 | | 0 | Success | |
| 110 | | 1 | Validation error (invalid name, branch not found, etc.) | |