Git Worktree management for parallel agent execution - isolated working directories without Git conflicts.

Use case: You want multiple Claude agents working on different features simultaneously. Without isolation, agents would conflict on git operations (commits, staging, file changes). With worktrees, each agent gets its own isolated directory.

Git worktrees allow multiple branches to be checked out simultaneously in different directories:

• Separate directory - No file access conflicts
• Separate index - Independent staging area
• Separate HEAD - Parallel commits possible

This is perfect for parallel agent execution where each agent needs its own isolated environment.

claude plugin marketplace add Marcel-Bich/marcel-bich-claude-marketplace
claude plugin install hydra@marcel-bich-claude-marketplace

# 1. Create worktrees for features
/hydra:create feature-login
/hydra:create feature-logout

# 2. Start agents in parallel
/hydra:parallel feature-login:Implement login form | feature-logout:Implement logout button

# 3. Check status
/hydra:status

# 4. Merge when done
/hydra:merge feature-login
/hydra:merge feature-logout

# 5. Monitor progress
/hydra:watch

# 6. Cleanup
/hydra:cleanup

# Create worktree
/hydra:create bugfix-123

# Spawn agent
/hydra:spawn bugfix-123 Fix the authentication bug in login.ts

# Check progress
/hydra:status bugfix-123

# Merge and cleanup
/hydra:merge bugfix-123
/hydra:delete bugfix-123

Creates a new worktree with a dedicated branch.

/hydra:create feature-name

• Creates branch hydra/feature-name
• Creates directory ../{repo}-worktrees/feature-name/
• Branch starts from current HEAD
• Runs scripts/worktree-setup.sh right after git worktree add, so the worktree gets the excluded files (see Worktree setup)

Shows all worktrees with their paths and branches.

/hydra:list

Output:

Git Worktrees:

  Path                              Branch              Commit
  ----------------------------------------------------------------
  /home/user/project                main                a1b2c3d
  /home/user/project-worktrees/a    hydra/feature-a     d4e5f6g

Shows detailed status including uncommitted changes and ahead/behind info.

/hydra:status              # All worktrees
/hydra:status feature-a    # Specific worktree

Safely removes a worktree with protection against data loss.

/hydra:delete feature-name

• Warns about uncommitted changes
• Asks for confirmation before deletion
• Optionally deletes the branch too

Starts a Claude agent in an existing worktree.

/hydra:spawn feature-name Implement the new dashboard component

• Agent works in isolated directory
• Agent commits its changes in the worktree
• Can run in background
• The agent is told the main checkout path: anything important missing in the worktree may be looked up there read-only (never written, committed or changed with git there); missing files are mentioned in the report so the worktree files list can be extended

Starts multiple agents simultaneously in different worktrees.

/hydra:parallel feature-a:Task A | feature-b:Task B | feature-c:Task C

• Creates missing worktrees automatically (each followed by worktree-setup.sh)
• All agents run in parallel
• Returns agent IDs for tracking

Merges a worktree branch back into the current branch.

/hydra:merge feature-name         # Default: merge
/hydra:merge feature-name rebase  # Alternative: rebase

• Shows what will be merged before proceeding
• Handles conflicts with clear instructions
• Blocks if uncommitted changes in current directory

Removes worktrees whose branches have been fully merged.

/hydra:cleanup            # Remove merged worktrees
/hydra:cleanup --dry-run  # Show what would be removed

• Only removes worktrees whose branch is fully merged into the main branch (the branch checked out in the main worktree) and that have no changes to tracked files; untracked scratch and the setup links go with them
• Keeps the main worktree, the current one, locked, unmerged and dirty worktrees, and a never-committed worktree younger than 24h or holding untracked files (an agent may be starting in it)
• Asks for confirmation
• Uses git worktree remove --force only for verified candidates (git unlinks symlinks, never follows them) and git branch -d

With credo installed, the same cleanup runs automatically whenever an item is closed, controlled by - [x] clean up merged worktrees automatically in the ### Hydra subsection of DOGMA-PERMISSIONS.md ([x] remove without asking, [?] or no checkbox ask, [ ] never). credo's credo-worktree-cleanup.sh implements the checks; every run covers all worktrees, so older ones are swept too.

Live monitoring of all background agents with auto-refresh.

/hydra:watch              # Monitor all running agents
/hydra:watch 5            # Refresh every 5 seconds (default: 3)

Features:

• Auto-refreshing status table
• Detects blocked agents (permission requests, errors)
• Shows agent ID, worktree, status, and last activity
• Prompts user when agents need attention

Status indicators:

• RUNNING - Agent is actively working
• BLOCKED - Agent waiting for permission/user input
• COMPLETED - Agent finished successfully
• FAILED - Agent encountered an error

Exit conditions:

• All agents completed
• User presses Ctrl+C
• Blocked agent requires intervention

Worktrees are created in a sibling directory to avoid cluttering the main repo:

/home/user/
  my-project/                    # Main repository
    .git/
    src/
    ...
  my-project-worktrees/          # Worktree container
    feature-a/                   # Worktree 1
      src/
      ...
    feature-b/                   # Worktree 2
      src/
      ...

Each worktree has:

• Its own working directory
• Its own staging area (index)
• Its own HEAD (current commit)
• Shared .git data with main repo (saves space)

A fresh worktree only contains versioned files. Excluded files such as CLAUDE.md, CLAUDE/, GUIDES/, DOGMA-PERMISSIONS.md or the .credo/ tree are missing, so an agent there would miss the project rules and items. scripts/worktree-setup.sh <worktree-path> [main-checkout] fixes that and runs automatically in /hydra:create and /hydra:parallel:

• The list comes from dogma's worktree-files.sh when dogma is installed (newest installed version) - the "Worktree files" list in the ### Hydra subsection of DOGMA-PERMISSIONS.md, e.g. - link: CLAUDE.md, - copy: .env.local. Without dogma, or when the list is missing or empty, the default applies: link CLAUDE.md, CLAUDE/, GUIDES/, DOGMA-PERMISSIONS.md and everything unversioned under .credo/, each only if it exists in the main checkout.
• link (default kind) creates a relative symlink to the main checkout; copy makes a separate copy for files that must differ per worktree.
• Only ignored paths are linked or copied. An untracked path that is not ignored in the main checkout (e.g. a new uncommitted credo item file) is skipped with skipped <path> (untracked, not ignored - read it in the main checkout): a git add -A in the worktree would commit the symlink, and merging would put it into the main branch where the path is a real file. Agents read such paths read-only in the main checkout (main=). They are never added to the shared .git/info/exclude, which would hide them in the main checkout too.
• A directory without tracked files is linked as a whole when it is ignored; a directory with tracked files inside (or a not-ignored one holding ignored entries) is recursed into and each untracked entry is handled individually (tracked ones come with the checkout).
• Versioned paths are skipped with a warning; an existing path in the worktree is never overwritten; nested repositories are skipped.
• A linked directory that is ignored only by a dir/ pattern gets an anchored /dir line in the shared .git/info/exclude, because a dir/ pattern does not match a symlink (otherwise it would show as untracked in the worktree).
• Output: linked, copied, kept ... (exists), skipped ... (versioned), skipped ... (untracked, not ignored - read it in the main checkout) lines, then source=dogma|default and main=<main checkout path>.

Symlinks also work on WSL with the repo on an NTFS drive (/mnt/c): WSL creates real NTFS symlinks that Windows can read.

credo ships the same logic as credo-worktree-setup.sh for its native flow. With credo and [x] use Hydra for 2+ independent tasks, credo uses hydra's flow for parallel code tracks automatically.

While hydra is installed, a PreToolUse hook keeps worktree creation on hydra's flow. It is active while the Hydra checkbox use Hydra for 2+ independent tasks in DOGMA-PERMISSIONS.md is on. A missing checkbox or file counts as on; [ ] or [0] switch the guard off, [?] (ask) lets the calls through.

• The Agent (or Task) tool with isolation: "worktree" is denied.
• EnterWorktree without a path is denied. With a path it enters an existing worktree and is allowed.
• git worktree add is denied unless the destination is ../<repo>-worktrees/<name> next to the main checkout. Shell variables and globs in the destination are denied; write the path literally.

The guard does not depend on the number of tracks: a single isolated track goes through hydra as well, not only 2+ parallel tasks. The deny message names the flow to use (/hydra:create <name>). The guard fails open (an internal error allows the call), needs python3 and makes no network calls.

1. One feature per worktree - Keep worktrees focused
2. Commit before merging - Ensure agent commits its work
3. Check status regularly - Use /hydra:status to monitor progress
4. Cleanup after merging - Remove merged worktrees to keep things tidy (automatic at item close with credo)
5. Use descriptive names - feature-login is better than wt1

• Worktrees share the same remotes and refs
• Cannot have same branch checked out in multiple worktrees
• Large repos may be slow to create worktrees (hard links help)

If a worktree is locked:

git worktree unlock <path>

If the branch already exists:

# Use existing branch
git worktree add <path> <existing-branch>

Remove the directory first or use a different name.

MIT - See LICENSE for full terms.

Tags: Claude Code, Git Worktree, Parallel Agents, Isolation, Branch Management, Multi-Agent, Concurrent Development, Hydra

Author: Marcel Bich