skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
onsager-ai/dev-skills63 installs

parallel-worktrees

Use for parallel agent sessions with git worktree, coordinating isolated branches and pull requests, or isolated dev stacks per branch behind a local proxy.

How do I install this agent skill?

npx skills add https://github.com/onsager-ai/dev-skills --skill parallel-worktrees
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    This skill provides a set of tools and documentation for managing multiple AI agent sessions in parallel using git worktrees and isolated Docker-based development environments. It uses standard tools like Docker, Git, and the GitHub CLI to maintain isolation and safety.

  • Socketwarn

    1 alert: gptSecurity

  • Snykfail

    Risk: CRITICAL · 3 issues

What does this agent skill do?

Parallel Worktrees

Run multiple AI coding sessions in parallel — each isolated in its own git worktree, pushing to its own branch, opening its own PR.

When to Use This Skill

Activate when:

  • User wants to run two or more AI agents on different features/bugs at once
  • User asks about git worktree for agent sessions
  • User wants parallel PRs from a single repo without multiple clones
  • User needs to set up, coordinate, or clean up concurrent agent workspaces

Decision Tree

What does the user need?

Start a new parallel session?
  → Create a worktree + branch (Lifecycle §1–2)
  → Open a terminal/agent session pointed at the worktree path
  → Brief the agent: "Work only in <worktree-path>. Branch: <branch-name>."

Push and open a PR?
  → git push -u origin <branch>
  → gh pr create (GitHub PR Sync reference)
  → Note related PRs in the description

Sync a worktree with the latest main?
  → Inside the worktree: git fetch origin && git rebase origin/main
  → Never merge across worktrees directly

Merge and clean up?
  → Merge PR on GitHub
  → git worktree remove <path> && git branch -d <branch>
  → git worktree prune

Hit an error?
  → "already checked out" → branch open elsewhere; use a new branch name
  → ".git/index.lock" → two processes on same worktree; one agent per worktree
  → Detached HEAD → git switch -c <new-branch> inside the worktree
  → Stale entry after dir deleted → git worktree prune

Core Concepts

Worktree vs clone — A worktree shares the same .git directory as the main checkout. No double-fetch, no disk waste. Each worktree checks out a different branch. Isolated at the filesystem level; same object store.

One agent, one worktree, one branch — This is the cardinal rule. Two agents sharing a worktree will corrupt each other's index. Two agents on the same branch will produce conflicting history.

PRs as the coordination channel — Agents communicate intent through PR titles, descriptions, and comments — not through shared files or direct worktree reads.

Layout Convention

Keep worktrees as siblings of the repo root to avoid .gitignore noise:

~/projects/
  myrepo/              ← main checkout (main branch)
  myrepo-wt/           ← worktree root (sibling dir)
    feat/auth/         ← worktree for branch feat/auth
    fix/login-bug/     ← worktree for branch fix/login-bug

Lifecycle

1. Create a worktree

# New branch (most common)
git worktree add ../myrepo-wt/feat/auth -b feat/auth

# From an existing remote branch
git worktree add ../myrepo-wt/fix/login-bug origin/fix/login-bug

2. Brief the agent

Give the agent its workspace clearly:

Working directory: /home/user/projects/myrepo-wt/feat/auth
Branch: feat/auth
Scope: implement JWT authentication — do not touch files outside this scope

The agent operates entirely within this directory. It should have no awareness of other worktrees.

3. Work and commit

Normal git flow inside the worktree — the agent uses git add, git commit as usual. The branch is isolated from main and all sibling worktrees.

4. Push and open PR

git push -u origin feat/auth
gh pr create \
  --title "feat(auth): implement JWT login" \
  --body "Parallel session. Related: #<pr-number> (if any)."

See references/github-pr-sync.md for draft PRs, PR templates, and linking.

5. Sync with main

# Inside the worktree
git fetch origin
git rebase origin/main   # keep history linear

Run this before opening a PR and before the final merge.

6. Merge and clean up

After the PR merges on GitHub:

# From the main repo (not inside the worktree)
git worktree remove ../myrepo-wt/feat/auth
git branch -d feat/auth
git worktree prune          # removes stale metadata entries

Branch Naming

Use a consistent pattern so agents (and humans) can parse ownership at a glance:

<type>/<scope>/<short-description>

feat/auth/jwt-login
fix/api/null-pointer
chore/deps/upgrade-pnpm
agent/experiment/refactor-parser   ← for exploratory agent sessions

Pitfalls

SymptomCauseFix
fatal: 'branch' is already checked outBranch open in another worktreeUse a new branch name
.git/index.lock errorsTwo processes on same worktreeOne agent per worktree
Detached HEADCreated from a commit SHA, not a branchgit switch -c <new-branch>
Worktree path gone after rebootDir deleted externallygit worktree prune, then recreate
git worktree list shows stale entriesDir removed without git worktree removegit worktree prune
Agent edits files in main checkoutAgent not scoped to worktree pathRe-brief agent with explicit working directory

References

Read these when you need more depth:

  • references/worktree-lifecycle.md — Full command reference, flags, edge cases (multiple worktrees, bare repos, moving worktrees)
  • references/github-pr-sync.md — PR creation, draft PRs, linking, status checks, merge strategies via gh CLI
  • references/agent-coordination.md — Patterns for coordinating output across parallel sessions: sequencing, handoffs, shared state via PRs

Optional add-ons

Repository hooks

Repository-managed commit and checkout guardrails are generated from the consumer manifest. See repository hooks.

Dev proxy

Run an isolated Compose stack per worktree behind a shared Traefik proxy, or route host-run dev stacks through it. See dev proxy for machine setup, repo onboarding, daily use, host-run stacks, and troubleshooting.

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/onsager-ai/dev-skills/parallel-worktrees">View parallel-worktrees on skillZs</a>