worktree

Creates isolated git worktrees with dedicated branches and ports for parallel agent sessions.

Updated Mar 26, 2026
One-click install
npx skills add https://github.com/levori119/skyboard --skill worktree-levori119
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: worktree
Source: https://github.com/levori119/skyboard/tree/main/.claude/skills/worktree
Command: npx skills add https://github.com/levori119/skyboard --skill worktree-levori119

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When multiple AI agents or sessions work on the same repository simultaneously, they silently overwrite each other's files, produce empty or mixed commits, and break shared builds. This Skill enforces a strict isolation rule: every agent works in its own git worktree on its own branch, eliminating silent data loss and cross-agent interference. ## Core Features & Use Cases - Isolation Detection: Checks git worktree list, git status, and current branch to determine whether the tree is shared before writing any code. - Worktree Provisioning: Creates ../skyboard-<name> with a dedicated feature/<name> branch, copies the gitignored .env, and relies on symlinked node_modules. - Port & Database Coordination: Assigns distinct API/Vite ports per worktree to avoid EADDRINUSE, and constrains shared-database migrations to additive ADD COLUMN IF NOT EXISTS changes. - Safe Teardown: Verifies only own files before commit, then removes the worktree and prunes stale registrations after merge. - Use Case: An agent starting a zone-limits feature runs the skill, gets its own worktree on ports 3002/5001, develops and tests in isolation, and merges without touching another agent's in-progress files. ## Quick Start Ask the agent to set up an isolated git worktree for the new feature before writing any code, for example by invoking /worktree zone-limits.

Frequently Asked Questions about worktree

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

FAQPage Schema
How do I run multiple AI agents on the same git repository safely?

Give each agent its own git worktree on its own branch using `git worktree add ../skyboard-<name> -b feature/<name>`. All reads, writes, tests, and commits then happen inside that directory, so agents never overwrite each other's files.

How to set up a git worktree for a new feature branch?

Run `git worktree add ../skyboard-<name> -b feature/<name>` from the main repo, then copy `.env` into the new directory since gitignored files do not transfer. node_modules is symlinked automatically, so no npm install is needed.

Why does git refuse to create a worktree on my branch?

Git rejects a worktree when the branch is already checked out elsewhere, reporting 'branch is already checked out'. Create a dedicated branch per worktree, such as `feature/<name>`, to resolve the conflict.

Can two worktrees share the same database for migrations?

Yes, but migrations affect all worktrees since they share one database. Use only additive changes like `ADD COLUMN IF NOT EXISTS`, never DROP or ALTER TYPE on columns other agents read, and coordinate through the user before touching shared tables.

Why do I get EADDRINUSE when running dev servers in parallel worktrees?

Two worktrees are bound to the same port. Assign each worktree distinct API and Vite ports (e.g., 3001/5000, 3002/5001) and point the Vite proxy at its own worktree's API port.

How do I clean up a git worktree after merging?

Run `git worktree remove ../skyboard-<name>`, delete the branch with `git branch -d feature/<name>`, then `git worktree prune` to clear stale registrations from manually deleted folders.