worktree-agent

Enforce git worktree isolation rules for parallel agent execution.

415|44|Updated Mar 18, 2026
One-click install
npx skills add https://github.com/notque/vexjoy-agent --skill worktree-agent-notque
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: worktree-agent
Source: https://github.com/notque/vexjoy-agent/tree/main/skills/process/worktree-agent
Command: npx skills add https://github.com/notque/vexjoy-agent --skill worktree-agent-notque

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

It prevents agent workflows from contaminating the main repository by enforcing strict git worktree isolation rules, including safe branching, path handling, and evidence-backed changes.

Core Features & Use Cases

  • Working directory verification: Ensures the agent runs inside .claude/worktrees/ and halts if it’s operating from the main repo path.
  • Branching and staging safety: Forces feature-branch creation before work begins and restricts git add to specific files only, avoiding accidental broad changes.
  • Commit and CI/lint gate compliance: Requires conventional commit formatting and runs both ruff check and ruff format --check for Python changes to avoid CI failures.
  • PR contamination prevention: Blocks cross-agent context leakage by preventing edits outside the worktree and disallowing unsafe operations in the main repo.

Quick Start

Start an agent with isolation set to worktree and follow the rules to verify you’re in the correct worktree path before creating a feature branch, staging only the intended files, and running both Ruff checks before delivering results.

Frequently Asked Questions about worktree-agent

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

FAQPage Schema
How do I isolate parallel agents from contaminating my main git repository?

Git worktree isolation prevents agents from contaminating the main repository by enforcing mandatory worktree creation, feature branching, and restricted file staging within a dedicated `.claude/worktrees/` directory.

What's the best way to prevent agents from accidentally staging unintended files in git?

Restrict `git add` to specific files only. Worktree isolation rules enforce staging only the intended files to prevent accidental broad changes and cross-agent context leakage during parallel execution.

How do I run isolated agents in git worktrees without causing CI failures?

To avoid CI failures, isolated agents in git worktrees must pass both `ruff check` and `ruff format --check` for Python changes before delivering results and follow conventional commit formatting.

Does worktree isolation work with parallel agent execution using auto-planning?

Yes, worktree isolation applies to parallel agent execution scenarios using `isolation: "worktree"`. It safely routes tasks that may auto-plan by ensuring safe branching, staging, and worktree-relative path handling.

Why does my agent workflow halt when starting from the main repository path?

Agent workflows halt to prevent PR contamination. Worktree isolation requires starting in a `.claude/worktrees/` CWD and blocks execution if it detects the agent is operating from the main repo path.

Do I need to create a feature branch before committing changes in an isolated worktree?

Yes, worktree isolation rules force feature-branch creation before work begins. This ensures safe branching and evidence-backed changes, preventing non-reproducible commits in parallel agent execution.