git-worktree-prepare

Create or reuse isolated git worktrees for target branches.

5|Updated Jan 25, 2026
One-click install
npx skills add https://github.com/f4irline/bbqparty-ai --skill git-worktree-prepare
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: git-worktree-prepare
Source: https://github.com/f4irline/bbqparty-ai/tree/main/packages/opencode/.opencode/skills/git-worktree-prepare
Command: npx skills add https://github.com/f4irline/bbqparty-ai --skill git-worktree-prepare

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill prevents branch checkout conflicts by creating or reusing isolated git worktrees for target branches so multiple agents or parallel processes can work concurrently without interfering with each other.

Core Features & Use Cases

  • Deterministic Path Layout: Always places worktrees under .opencode/.bbq-worktrees with branch names normalized by replacing slashes with dashes.
  • Safe Creation & Reuse: Detects an existing attached worktree for a branch and reuses it, or creates a new tracked branch or branch from the remote default when needed.
  • Local-only File Syncing: Mirrors repository-local files listed in .opencode/worktree-local-files into new worktrees using symlinks with copy fallbacks to keep environment files consistent.
  • Use Case: Ideal for ticket-driven development where multiple agents spin up parallel environments for features, automated CI tasks, or agent-based code workflows.

Quick Start

Run the skill with the target branch name to create or reuse the deterministic worktree path and sync local-only files into it.

Frequently Asked Questions about git-worktree-prepare

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

FAQPage Schema
How do I prevent git branch checkout conflicts when running parallel development tasks?

To prevent git branch checkout conflicts during parallel development, you can create or reuse isolated git worktrees for each target branch. This allows multiple agents or processes to work concurrently without interfering with each other's local checkout states.

What is the best way to automate git worktree creation for ticket-based workflows?

Automating git worktree creation for ticket-based workflows involves resolving the repository root and remote default branch, then building a deterministic worktree path. This path is consistently generated under a dedicated directory with branch names normalized by replacing slashes with dashes.

How do I sync local-only environment files into a new git worktree?

To sync local-only environment files into a new git worktree, you mirror repository-local files listed in a specific configuration file into the new worktree. This is typically done using symlinks with copy fallbacks to keep environment files consistent across isolated branches.

Does git worktree management support reusing existing branches for automated agents?

Yes, git worktree management supports reusing existing branches for automated agents by detecting an existing attached worktree for a target branch and reusing it. If not found, it creates a new tracked branch or branches from the remote default.

Why does my parallel agent workflow interfere with the main git repository checkout?

Your parallel agent workflow interferes with the main git repository checkout because multiple processes are sharing the same working directory. Creating dedicated git worktrees provides isolated branch checkouts, preventing processes from overwriting each other's uncommitted changes.

What are the limitations of using symlinks to sync local files in git worktrees?

A limitation of using symlinks to sync local files in git worktrees is potential filesystem or platform incompatibility where symlinks are unsupported. In these cases, the system must fall back to copying files, which may lead to desynchronization if the original local files are modified later.