worktrees

Orchestrates Git worktrees as isolated coding lanes for parallel and risky development work.

Updated Jun 16, 2022
One-click install
npx skills add https://github.com/SimonZimmer/dotfiles --skill worktrees-simonzimmer
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: worktrees
Source: https://github.com/SimonZimmer/dotfiles/tree/main/.config/opencode/skills/worktrees
Command: npx skills add https://github.com/SimonZimmer/dotfiles --skill worktrees-simonzimmer

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Managing parallel branches, risky refactors, or background agent tasks in a single Git checkout leads to context switching, half-committed work, and broken working environments. This Skill provides a structured protocol for creating, tracking, integrating, and cleaning up Git worktrees as isolated coding lanes. ## Core Features & Use Cases - Safe Lane Setup: Creates worktrees under .slim/worktrees/<slug>/ with pre-flight checks, branch conflict detection, and managed .gitignore/.ignore blocks. - State Tracking: Maintains a .slim/worktrees.json manifest recording each lane's branch, path, purpose, owner, and status. - Guarded Integration & Cleanup: Enforces diff review, user confirmation before merges or destructive commands, and safe worktree removal with pruning. - Use Case: You need to refactor an authentication flow while keeping your main checkout stable. The Skill creates an isolated worktree lane, delegates work to sub-agents inside it, validates the diff against the base branch, and cleans up after an approved merge. ## Quick Start Ask the AI to create a new worktree lane for your feature, for example: set up an isolated worktree for refactoring the authentication module off the main branch.

Frequently Asked Questions about worktrees

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

FAQPage Schema
How do I create a Git worktree for parallel development?▼

Run git worktree add with a new branch and target path, such as git worktree add -b omos/my-feature .slim/worktrees/my-feature main. This Skill wraps that command with pre-flight checks, ignore-file setup, and metadata registration before execution.

When should I use Git worktrees instead of branches?▼

Use worktrees for risky refactors, parallel tasks, background agents, or exploratory spikes that would disrupt your active checkout. Avoid them for simple single-file changes, documentation updates, or minor bug fixes where a normal branch suffices.

Can multiple AI agents work in separate worktrees at once?▼

Yes. Each sub-agent runs with its working directory set to its own worktree path, keeping builds, tests, and edits isolated. File or folder ownership is tracked per lane to prevent merge conflicts between parallel agents.

How do I safely remove a Git worktree after merging?▼

First confirm all changes are merged or archived and the worktree has no uncommitted changes, then run git worktree remove with the lane path. This Skill requires explicit user approval before removal and updates the tracking manifest afterward.

Why should worktrees not be created as sibling directories of the repository?▼

Placing worktrees inside .slim/worktrees/ keeps lane artifacts contained and lets gitignore and ignore-file rules manage them consistently. Sibling-directory worktrees scatter state outside the project's controlled ignore configuration.