worktree-create
Create isolated git worktrees for parallel development. Use when working on multiple issues simultaneously.
When & Why to Use This Skill
This Claude skill automates the creation of isolated Git worktrees, enabling developers to manage multiple branches simultaneously in separate directories. By eliminating the need for frequent stashing and context switching, it streamlines parallel development workflows and enhances productivity during complex software engineering tasks.
Use Cases
- Parallel Feature Development: Work on a new feature in one directory while keeping a separate environment open for urgent bug fixes or hotfixes.
- Context Switch Reduction: Avoid the overhead of 'git stash' and 'git checkout' by maintaining physical separation between different issue-specific environments.
- Cross-Branch Testing and Comparison: Run long-running test suites or build processes in one worktree while continuing active development in another, or compare different implementations side-by-side.
- Multi-Phase Project Management: Organize complex tasks into dedicated worktrees for planning, implementation, and testing to maintain a clean and logical project structure.
| name | worktree-create |
|---|---|
| description | "Create isolated git worktrees for parallel development. Use when working on multiple issues simultaneously." |
| mcp_fallback | none |
| category | worktree |
Worktree Create
Create separate working directories on different branches without stashing changes.
When to Use
- Starting work on a new issue
- Need to work on multiple issues in parallel
- Want to avoid stashing/context switching overhead
- Testing changes across different branches
Quick Reference
# Create worktree for new branch
./scripts/create_worktree.sh <issue-number> <description>
# Example
./scripts/create_worktree.sh 42 "implement-tensor-ops"
# Creates: ../ProjectOdyssey-42-implement-tensor-ops/
# List all worktrees
git worktree list
# Switch worktrees
cd ../ProjectOdyssey-42-implement-tensor-ops
Workflow
- Create worktree - Run create script with issue number and description
- Navigate -
cdto new worktree directory (parallel to main) - Work normally - Make changes, commit, push as usual
- Switch back -
cdto different worktree or main directory - Clean up - Remove worktree after PR merge (see
worktree-cleanupskill)
Error Handling
| Error | Solution |
|---|---|
| Branch already exists | Use different branch name or delete old branch |
| Directory exists | Choose different location or remove directory |
| Cannot switch away | Ensure all changes are committed |
| Permission denied | Check directory permissions |
Directory Structure
parent-directory/
├── ProjectOdyssey/ # Main worktree (main branch)
├── ProjectOdyssey-42-tensor-ops/ # Issue #42 worktree
├── ProjectOdyssey-73-bugfix/ # Issue #73 worktree
└── ProjectOdyssey-99-experiment/ # Experimental worktree
Best Practices
- One worktree per issue (don't share branches)
- Use descriptive names:
<issue-number>-<description> - All worktrees share same
.gitdirectory - Clean up after PR merge
- Each branch can only be checked out in ONE worktree
Multi-Issue Parallel Development
When working on related issues (e.g., Plan → Test/Impl/Package → Cleanup phases):
Phase-Based Worktree Pattern
# Phase 1: Plan (sequential, must complete first)
git worktree add ../ProjectOdyssey-62-plan-agents 62-plan-agents
# Phase 2: Parallel development (after Plan complete)
git worktree add ../ProjectOdyssey-63-test-agents 63-test-agents
git worktree add ../ProjectOdyssey-64-impl-agents 64-impl-agents
git worktree add ../ProjectOdyssey-65-pkg-agents 65-pkg-agents
# Phase 3: Cleanup (after parallel phases complete)
git worktree add ../ProjectOdyssey-66-cleanup-agents 66-cleanup-agents
Coordination Patterns
- Test and Impl coordinate for TDD (test-first development)
- Package integrates Test and Impl artifacts
- All worktrees reference the same Plan specifications
- Cleanup merges all parallel work and resolves issues
PR Strategy
Recommended: One PR per Phase
- PR 1: Plan issues → Merge specifications together
- PR 2: Test/Impl/Package → Merge implementation together
- PR 3: Cleanup → Final polish
Advantages: Logical grouping, easier review, clear milestones
References
scripts/create_worktree.shimplementation- See
worktree-cleanupskill for removing worktrees - See
worktree-syncskill for keeping worktrees up to date