worktrees

Create isolated git worktrees for parallel development tasks.

48|8|Updated Oct 17, 2025
One-click install
npx skills add https://github.com/maragudk/skills --skill worktrees
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: worktrees
Source: https://github.com/maragudk/skills/tree/main/worktrees
Command: npx skills add https://github.com/maragudk/skills --skill worktrees

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires lsof, docker, and includes scripts (resource) components.

What problem does it solve?

This Skill enables parallel development by using git worktrees, letting multiple agents work on different features simultaneously in isolation without interfering with the main working directory.

Core Features & Use Cases

  • Isolated worktrees: Create .worktrees/<branch-name> with its own checked-out branch.
  • Parallel development: Work on multiple features in parallel without stashing or switching contexts.
  • Management: List active worktrees and safely remove them when done (see also apps.md for services).
  • Notes: Keep ports and services isolated per worktree when applicable.

Quick Start

From the main repository, create a new worktree for your feature: git worktree add .worktrees/<branch-name> -b <branch-name> Change into the new worktree: cd .worktrees/<branch-name> Start working in isolation and commit as you would in the main repo.

Frequently Asked Questions about worktrees

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

FAQPage Schema
How do I set up parallel git worktrees for simultaneous feature development?

Git worktrees enable parallel development by creating isolated branch checkouts in separate directories. Use `git worktree add .worktrees/<branch-name> -b <branch-name>` to create a new worktree, then `cd .worktrees/<branch-name>` to work in isolation without affecting your main directory or stashing changes.

What's the benefit of using git worktrees instead of switching branches?

Worktrees let multiple agents work on different features concurrently in separate directories without context switching, stashing, or conflicts. Each worktree maintains its own checked-out branch and environment, enabling truly parallel development workflows.

How do I manage environment variables and services across multiple worktrees?

Git worktrees support per-worktree `.env` handling and optional service startup scripts, keeping ports and services isolated per worktree. This prevents cross-worktree interference and lets each isolated environment run independently.

Can I list and remove git worktrees safely?

Yes. List active worktrees with `git worktree list` to see all branches and their locations. Remove completed worktrees with `git worktree remove <path>` once work is finished, cleaning up the isolated directory structure.

What are the limitations of git worktrees in automation workflows?

Worktrees require lsof and docker as dependencies for full integration. Port and service conflicts can occur if isolation isn't properly enforced across worktrees, so environment management and per-worktree configuration are essential for reliable parallel automation.