Documentation / Worktrees vs. loose instances

Worktrees vs. loose instances

Mulpex has two kinds of Claude tab. Pick based on whether the work needs its own branch.

Worktree (the default — ⌘T)

Each worktree instance lives in its own git worktree at <project>/.mulpex/worktrees/<id>/ on a branch named mulpex/<id>, branched from the project's current HEAD. Claude only sees that worktree's files, so multiple worktree tabs in the same project work in parallel without colliding.

Worktrees persist across app restarts. Closing a tab with unmerged work doesn't destroy the worktree — the instance goes dormant and can be revived from the sidebar. The only paths that actually delete a worktree are explicit Discard, a successful Merge, and /exit from a clean session with no commits.

Use a worktree when: you're building a feature, fixing a bug, or doing anything you might want to merge to main.

Loose (⌘⇧T)

A loose instance runs in the project's actual checkout — not a worktree. File edits go to whatever branch is currently checked out, and there's no branch isolation between loose tabs. Loose is reachable via project right-click → New Loose Claude, the File menu, or ⌘⇧T against the selected project.

Loose tabs are marked with a ⚡ glyph and an italic title in the sidebar so you can tell them apart at a glance.

Use loose when: the work is one-off and doesn't belong on its own branch — checking what tools or skills are installed, debugging why a dev server won't bind to a port, asking Claude about the codebase without intending to commit anything. If you change your mind, right-click the loose instance and pick Convert to Worktree to promote it in place — the session, name, and any attached runbooks carry over.

Quick rule

If you'd be embarrassed to commit the work to a branch with your name on it, use a worktree. If the work isn't a commit at all, use loose.