worktree-fleet

Run parallel agents in isolated git worktrees with overlap validation.

1|Updated Apr 16, 2026
One-click install
npx skills add https://github.com/quickcall-dev/skills --skill worktree-fleet
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: worktree-fleet
Source: https://github.com/quickcall-dev/skills/tree/main/skills/worktree-fleet
Command: npx skills add https://github.com/quickcall-dev/skills --skill worktree-fleet

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires jq, git, tmux, python3, stat, pgrep, and includes scripts (resource) and references (resource) components.

What problem does it solve?

worktree-fleet prevents parallel agent edits from colliding by isolating each worker in its own git worktree and branch, then validating that workers do not overlap on the files they claim to touch.

Core Features & Use Cases

  • Independence validation before spawning: the skill refuses to launch when any two workers’ declared target_files overlap (including glob overlap), protecting you from irreversible merge conflicts.
  • Merge-safe parallel execution: each worker runs on its own branch/worktree (claude -p, codex exec, or pi -p) so changes are independently captured and inspectable.
  • Operator-controlled merging: after completion, you generate a merge plan and manually merge according to the constraints of parallel work.

Use when: refactoring multiple modules at once, updating separate docs, or making concurrent changes across non-overlapping parts of a repo where you still want git history and clean separation.

Quick Start

Launch a merge-safe parallel fleet by creating a fleet.json with distinct target_files per worker, writing a prompt.md for each worker, then running bash ${AGENTS_SKILLS_DIR}/scripts/launch.sh /absolute/path/to/fleet-root.

Frequently Asked Questions about worktree-fleet

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

FAQPage Schema
How do I run parallel git worktrees to prevent merge conflicts when editing multiple modules?

Git worktree isolation for parallel agents works by spawning each worker in a separate branch and worktree, then validating non-overlapping target files. This prevents irreversible merge conflicts by ensuring workers only edit distinct file globs before they are launched.

What is the best way to orchestrate multiple AI agents working on separate files in the same repository?

Orchestrating multiple AI agents on separate files requires declaring distinct target_files per worker in a fleet.json configuration. The system validates file glob overlaps before launch, spawning each agent in an isolated git worktree and branch for safe parallel execution.

Do I need tmux to spawn parallel workers in isolated git worktrees?

Yes, tmux is required to spawn parallel workers in isolated git worktrees. The orchestration process uses tmux-based worker spawning alongside dependencies including jq, git, python3, stat, and pgrep to manage independent agent sessions.

How do I validate branch isolation before launching parallel git work?

You validate branch isolation by running a mandatory dry-run validation that detects file glob overlaps across workers' declared target_files. The system refuses to launch when any two workers' globs overlap, ensuring safe orchestration before spawning.

Can I use parallel git worktrees for concurrent documentation updates and refactoring?

Yes, parallel git worktrees support concurrent documentation updates and refactoring tasks. This approach applies to one-shot parallel tasks where workers edit non-overlapping file globs, capturing changes as separate commits in isolated branches for clean git history.

Why does parallel agent orchestration fail when workers target overlapping files?

Parallel agent orchestration refuses to launch when workers' declared target_files overlap to prevent irreversible merge conflicts. The system detects glob pattern overlaps during pre-launch independence validation, enforcing strict file isolation for safe orchestration.