Git Worktree Agent

Managing parallel features in a single repository often leads to messy stashes or risky branch switching that breaks build artifacts. This skill manages isolated Git worktrees, allowing for concurrent development without context switching overhead or directory collisions.

What it does

• Parallel workspace management isolates features or bug fixes into dedicated directories to avoid git stash cycles.
• Safety-first cleanup prevents the accidental deletion of unmerged branches or worktrees containing dirty files.
• Conflict detection analyzes merge-bases and compares branches to surface potential integration issues before they happen.
• Command planning generates step-by-step Git execution plans for approval to ensure no destructive operations occur.
• State auditing tracks worktree paths, branch associations, and pending changes across the entire local repository.

How it works

1. Inspection of the current repository state including git status, branch list, and existing worktree paths.
2. Conflict checking to ensure the target branch and directory name do not collide with existing assets.
3. Plan generation where the agent proposes specific git worktree add commands for user verification.
4. Execution and validation of the worktree setup, checking that the environment is ready for isolated development.
5. Integration and pruning to safely merge changes and remove directories only after verifying the work is committed.

Frameworks & tools

This skill works with any standard Git installation. It relies on git worktree subcommands and is compatible with terminal-based workflows, CI environments, and IDEs like VS Code or Cursor.

Why this beats prompting it yourself

Generic prompts often suggest risky flags like --force or forget to check for untracked files before pruning. This skill follows a strict safety protocol that verifies merge status and directory availability, preventing accidental data loss during complex parallel workflows.

Use cases

• Manage a hotfix in a separate directory while keeping a long-running feature build intact.
• Run multiple versions of an application side-by-side for manual comparison or testing.
• Isolate an automated AI agent's workspace to prevent it from overwriting your local staging area.
• Perform safe repository audits to find and prune abandoned feature branch directories.

Known limitations

Requires Git 2.5 or newer. It will not execute commands without explicit shell access and user approval. It does not manage submodules unless specifically instructed.