git-worktrees

Manages parallel git worktrees for concurrent agents, isolated verification runs, and ordered branch merges.

Updated Aug 4, 2026
One-click install
npx skills add https://github.com/tschallacka/ai-skills --skill git-worktrees-tschallacka
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: git-worktrees
Source: https://github.com/tschallacka/ai-skills/tree/main/git-worktrees
Command: npx skills add https://github.com/tschallacka/ai-skills --skill git-worktrees-tschallacka

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When several agents or tasks work in one repository at once, they overwrite each other's files, long test runs pick up half-written edits, and merging everything back produces confusing conflicts. This Skill defines the rules for using git worktrees so parallel work stays isolated, verifications see a frozen tree, and branches merge back in a sane order. ## Core Features & Use Cases - Parallel agent isolation: One worktree and one task-named branch per agent, with disjoint file scopes, so concurrent work never silently clobbers another agent's edits. - Safe long-running verification: Guidance for the concurrency hazard where a harness sweeping stale worktrees deletes a live one mid-run, including a pid-file pattern to tell live checkouts from abandoned ones. - Ordered merge-back workflow: Merge one branch at a time in dependency order, regenerate build output instead of hand-merging it, and re-run tests after each merge. - Use Case: You coordinate three subagents fixing separate bugs in one repo. Each gets its own worktree under the shared worktrees root, branches from the same base, and you merge the branches back least-conflicting first, re-running the focused tests after each merge. ## Quick Start Create a separate git worktree and branch for each of my three agents under the standard worktrees directory, then merge their branches back one at a time in dependency order.

Frequently Asked Questions about git-worktrees

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
Where should git worktrees be created for agent workflows?▼

Place them under a dedicated directory such as ${XDG_CONFIG_HOME:-$HOME/.config}/tsch-ai-worktrees/, one named directory per task. Never use /tmp, a path inside the repository, or a directory holding private keys and installed binaries.

Why did my test suite fail with missing-file errors in a worktree?▼

A concurrent run likely deleted your worktree: harnesses that sweep stale worktrees cannot distinguish a live one from an abandoned one. Check for a parallel run, re-run alone, and use a pid-file check so cleanup skips worktrees whose owner process is alive.

How do I merge several parallel branches back into main?▼

Merge one branch at a time in dependency order, starting with branches touching shared or generated files, and re-run the tests after each merge. Regenerate build output like lock files rather than hand-merging it, since textually merged generated files look plausible but are wrong.

Why does git add -A cause problems with nested repositories?▼

git add -A stages a nested repository as a gitlink, a bare commit pointer with none of its content, so the commit looks fine but the nested work is missing. Stage explicit paths or use git add -u, and check git status --porcelain for an unexpected mode 160000 entry.

When should I remove a git worktree after a task finishes?▼

Remove it as the task's last step with git worktree remove, then git worktree prune. A leftover worktree gets inherited by the next task, which then starts from a stale commit hundreds of commits behind the tip with nothing flagging the staleness.