| name | worktree-workflow |
| description | Git worktree isolation for parallel development. Use EnterWorktree/ExitWorktree to create isolated branches for features, experiments, or risky changes. Auto-activates on worktree, parallel branches, isolated work, experiment in isolation, side branch, parallel feature. |
Worktree Workflow
Use git worktrees for parallel, isolated development without affecting the main working directory.
When to Use
- Parallel features: Work on multiple features simultaneously without stashing/switching
- Experiments: Try risky refactors or approaches in isolation — discard if they fail
- Hotfixes: Fix a bug on a release branch while feature work continues
- Investigation: Test a hypothesis about a bug without polluting the main branch
- A/B comparison: Compare two implementations side by side
Tools
EnterWorktree
Creates an isolated git worktree with a new branch based on HEAD.
Parameters:
name (optional) — Descriptive name for the worktree (e.g., fix-auth-bug, experiment-caching). Auto-generated if omitted.
Behavior:
- Creates worktree in
.claude/worktrees/<name>
- Creates a new branch from current HEAD
- Switches the session's working directory to the worktree
- Full git history available — commits, pushes, etc. all work normally
ExitWorktree
Leave the worktree and return to the original working directory.
Parameters:
action (required) — "keep" or "remove"
keep — Leave the worktree and branch on disk for laterremove — Delete the worktree directory and branch
discard_changes (optional) — Set true to force-remove even with uncommitted changes
Workflow Patterns
Experiment-then-Merge
EnterWorktree with descriptive name- Implement the experimental approach
- Run tests to validate
- If successful: commit, exit with
keep, merge from main branch
- If failed: exit with
remove to clean up
Parallel Feature Development
EnterWorktree for feature A- Implement feature A, commit
ExitWorktree with keepEnterWorktree for feature B- Implement feature B, commit
ExitWorktree with keep- Both branches exist independently — merge when ready
Safe Investigation
EnterWorktree to isolate investigation- Add debug logging, modify code freely
- Reproduce and diagnose the issue
ExitWorktree with remove (no mess left behind)- Apply the targeted fix in the main working directory
Constraints
- Must be in a git repository to use worktrees
- Cannot create a worktree while already in one (exit first)
- Uncommitted changes in worktree prevent
remove unless discard_changes: true
- On session exit while in a worktree, user is prompted to keep or remove
When NOT to Use Worktrees
- Simple branch switches — Use
git checkout or git switch instead
- Single-file experiments — Just edit and revert with
git checkout -- file
- Non-git projects — Worktrees require git
Best Practices
- Name worktrees descriptively:
fix-auth-timeout, experiment-redis-cache, hotfix-v2.1
- Commit meaningful work before exiting — uncommitted changes may be lost on remove
- Use
keep when you plan to return or merge; use remove for throwaway experiments
- Combine with
experiment-loop skill for metric-driven iteration in isolation
Related
experiment-loop skill — Autonomous optimization patterns (can run inside worktrees)git-workflow skill — Branch management and commit conventions/checkpoint command — Named save points (lighter weight than worktrees)
