git-worktrees skill
Enables parallel development by maintaining multiple checked-out branches simultaneously in separate, isolated directories.
- GitHub stars
- 44
- Files
- 1
- Last commit
- Apr 12, 2026
- License
- MIT
- Allowed tools
- —
What does the git-worktrees skill do?
git-worktrees enables parallel development by maintaining multiple checked-out branches simultaneously in separate, isolated directories.
Summary generated from the skill's SKILL.md.
About the git-worktrees skill
Managing multiple development tasks simultaneously without stashing changes or switching branches is what git-worktrees enables. Developers and AI orchestrators use this skill to create isolated directories for different branches, allowing for parallel work. This is particularly useful for subagent-driven development where multiple agents must operate on separate filesystems to avoid clobbering uncommitted changes.
An agent should load this skill when it needs to perform hotfix work while a feature branch is in progress or when it requires a clean checkout to run tests without local artifacts or build leftovers. The skill relies on standard git commands like git worktree add, list, remove, and prune. It produces independent workspaces tied to specific branches, ensuring that each task has its own environment for dependencies and local configurations.
What an agent can do with it
- 1Concurrent subagent developmentAssign multiple agents to work on different tasks at the same time without their files interfering with each other.
- 2Isolated testing baselinesVerify that tests pass on a fresh checkout that is free from local configuration or uncommitted changes.
- 3Parallel hotfix implementationAddress urgent bugs in a separate workspace while a long-running feature branch remains active.
- 4Side-by-side branch comparisonExamine the behavior and differences between two different branches in separate directories at once.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the git-worktrees skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the git-worktrees skill in Plugin
/plugin marketplace add itallstartedwithaidea/agent-skills /plugin install software-dev-skills@googleadsagent-skills
Install the git-worktrees skill in Claude Code
~/.claude/skills/git-worktrees/SKILL.md
$ npx degit itallstartedwithaidea/agent-skills/skills/software-dev/git-worktrees ~/.claude/skills/git-worktreesInstall the git-worktrees skill in Claude Code (project)
.claude/skills/git-worktrees/SKILL.md
$ npx degit itallstartedwithaidea/agent-skills/skills/software-dev/git-worktrees .claude/skills/git-worktreesInstall the git-worktrees skill in Codex
~/.agents/skills/git-worktrees/SKILL.md
$ npx degit itallstartedwithaidea/agent-skills/skills/software-dev/git-worktrees ~/.agents/skills/git-worktreesInstall the git-worktrees skill in Gemini CLI
~/.gemini/skills/git-worktrees/SKILL.md
$ npx degit itallstartedwithaidea/agent-skills/skills/software-dev/git-worktrees ~/.gemini/skills/git-worktreesInstall the git-worktrees skill in Claude.ai
npx degit itallstartedwithaidea/agent-skills/skills/software-dev/git-worktrees git-worktrees && zip -r git-worktrees.zip git-worktrees # claude.ai → Customize → Skills → + → Create skill → Upload a skill → git-worktrees.zip
SKILL.md
View on GitHubGit Worktrees
Part of Agent Skills™ by googleadsagent.ai™
Description
Git Worktrees enables parallel development by maintaining multiple checked-out branches simultaneously in separate directories. Instead of stashing changes and switching branches, the agent creates isolated worktrees for each task, providing clean test baselines and eliminating context-switching overhead. Each worktree is a fully independent workspace tied to its own branch.
This skill is essential for subagent-driven development, where multiple agents work on different tasks concurrently. Without worktrees, agents would clobber each other's uncommitted changes. With worktrees, each agent operates in its own directory with its own branch, and the orchestrator merges completed work back into the main line.
Worktrees also provide clean baselines for testing. When you need to verify that tests pass on a clean checkout—without build artifacts, local config, or uncommitted changes—a fresh worktree gives you exactly that. The worktree lifecycle is managed explicitly: create when a task starts, verify when it completes, and prune when it merges.
Use When
- Multiple tasks must be developed in parallel without interference
- Subagents need isolated filesystems for concurrent work
- You need a clean checkout to run tests without local artifacts
- Hotfix work must happen while a feature branch is in progress
- Best-of-N implementations need separate workspaces
- You want to compare behavior across branches side by side
How It Works
graph TD
A[Main Repo] --> B["git worktree add ../task-1 -b feature/task-1"]
A --> C["git worktree add ../task-2 -b feature/task-2"]
A --> D["git worktree add ../hotfix -b hotfix/urgent"]
B --> E[Agent 1 works in ../task-1]
C --> F[Agent 2 works in ../task-2]
D --> G[Agent 3 works in ../hotfix]
E --> H[PR + Merge]
F --> H
G --> H
H --> I["git worktree remove ../task-1"]
H --> J["git worktree remove ../task-2"]
H --> K["git worktree remove ../hotfix"]
Each worktree is a real directory on disk with its own checked-out branch. Changes in one worktree do not affect others. The .git metadata is shared, so branch operations (push, fetch, log) work normally from any worktree.
Implementation
# Create a worktree for a new feature
git worktree add ../feature-auth -b feature/user-auth
cd ../feature-auth
npm install # Dependencies may differ per branch
# List active worktrees
git worktree list
# /home/user/project abc1234 [main]
# /home/user/feature-auth def5678 [feature/user-auth]
# Run tests in a clean worktree
git worktree add ../clean-test --detach HEAD
cd ../clean-test
npm ci && npm test
cd ../project
git worktree remove ../clean-test
# Prune stale worktrees (after branch deletion)
git worktree prune
class WorktreeManager:
def __init__(self, repo_root):
self.repo_root = repo_root
self.worktree_base = Path(repo_root).parent
def create(self, task_name, base_branch="main"):
branch = f"feature/{task_name}"
path = self.worktree_base / task_name
subprocess.run(
["git", "worktree", "add", str(path), "-b", branch, base_branch],
cwd=self.repo_root, check=True
)
return WorktreeContext(path, branch)
def remove(self, task_name):
path = self.worktree_base / task_name
subprocess.run(
["git", "worktree", "remove", str(path)],
cwd=self.repo_root, check=True
)
def list_active(self):
result = subprocess.run(
["git", "worktree", "list", "--porcelain"],
cwd=self.repo_root, capture_output=True, text=True
)
return self.parse_worktree_list(result.stdout)
Best Practices
- Always create worktrees from the main repository, not from another worktree
- Run
npm cior equivalent in each new worktree—node_modulesare not shared - Remove worktrees promptly after merging to avoid disk bloat
- Use
git worktree pruneperiodically to clean up stale references - Name worktree directories descriptively to match their branch purpose
- Never checkout the same branch in two worktrees simultaneously
Platform Compatibility
| Platform | Support | Notes |
|---|---|---|
| Cursor | Full | best-of-n-runner uses worktrees natively |
| VS Code | Full | Multi-root workspace support |
| Windsurf | Full | Shell-based worktree management |
| Claude Code | Full | Direct git access |
| Cline | Full | Terminal git commands |
| aider | Full | Works from any worktree directory |
Related Skills
- Subagent-Driven Development - Parallel task dispatch that relies on worktrees for filesystem isolation between agents
- Executing Plans - Plan execution with rollback that uses worktrees for clean verification baselines
- Code Review - Pre-merge quality gate applied to each worktree branch before merging
Keywords
git-worktrees parallel-development isolated-workspace clean-baseline concurrent-branches subagent-isolation best-of-n branch-management
© 2026 googleadsagent.ai™ | Agent Skills™ | MIT License
Files in this skill
1git-worktrees skill questions
How do I install the git-worktrees skill in Claude Code?
Run npx degit itallstartedwithaidea/agent-skills/skills/software-dev/git-worktrees ~/.claude/skills/git-worktrees. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the git-worktrees skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
How do git worktrees help with concurrent agent tasks?
They provide isolated filesystems for subagents, preventing them from clobbering each other's uncommitted changes by giving each agent its own directory and branch.
Can I use worktrees to run tests without local interference?
Yes, creating a fresh worktree provides a clean checkout without build artifacts, local configurations, or uncommitted changes, which is ideal for verifying tests.
Are dependencies like node_modules shared between worktrees?
No, dependencies are not shared; you should run installation commands like npm ci in each new worktree.