Git Worktree Manager

Manage isolated Git worktrees for parallel development, following project conventions.

Quick Reference

Command	Description
`create <name> [base]`	Create worktree with symlinked .env
`list`	List all worktrees
`cleanup`	Remove inactive worktrees
`switch <name>`	Switch to a worktree

CRITICAL: Always Use the Manager Script

NEVER call
git worktree add
directly. Always use the script.

bash

# CORRECT
bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh create feature-name

# WRONG - Never do this directly
git worktree add .github/worktrees/feature-name -b feature-name develop

The script handles:

Symlinks
```
.env
```
file (not copy) from project root
Ensures
```
.github/worktrees/
```
is in
```
.gitignore
```
Creates consistent directory structure at
```
.github/worktrees/
```

CRITICAL: Create the Worktree, Then STOP

After creating a worktree, STOP. Do NOT implement anything in the current session. Do NOT

cd

into the worktree and keep working.

Your job in this session is ONLY:

Create the worktree
Show the user the copy-paste command from the script output
STOP and tell the user to run that command in a new terminal

All planning, brainstorming, and implementation happens in the new Claude Code instance inside the worktree — NOT here.

Why: Claude Code's working directory and statusline are set at launch time. If you work here after creating a worktree, auto-compact will lose the worktree context and revert to the main repo mid-work.

Project Conventions

Default base branch:
```
develop
```
(not
```
main
```
)
Symlinks for
```
.env
```
files, not copies — single source of truth
Worktree directory:
```
.github/worktrees/
```

Commands

create <branch-name> [from-branch]

Creates worktree in

.github/worktrees/<branch-name>

. Defaults to branching from

develop

bash

# Create from develop (default)
bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh create feature/pipeline-steps

# Create from specific branch
bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh create hotfix/auth main

What happens:

Checks if worktree exists
Creates
```
.github/worktrees/
```
directory if needed
Updates base branch from remote
Creates worktree and branch
Symlinks
.env
from project root
Verifies symlink
Outputs a copy-paste command to launch Claude Code in the worktree

list

ls

bash

bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh list

Shows:

Worktree name and branch
Current worktree marked with
```
*
```
Main repo status

switch <name>

go <name>

bash

bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh switch feature/pipeline-steps

cleanup

clean

Removes inactive worktrees interactively.

bash

bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh cleanup

Safety: Won't remove current worktree.

Workflow Examples

Feature Development

bash

# 1. Create worktree from develop
bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh create feature/auth-system

# Script output:
#   ━━━ Launch Claude Code in this worktree ━━━
#   cd /path/to/.github/worktrees/feature-auth-system && claude
#   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

# 2. CLAUDE STOPS HERE. Tells user to copy-paste the command above into a new terminal.
#    DO NOT continue with any work in this session.

# 3. User pastes command → new Claude Code instance starts in the worktree
#    User brainstorms, plans, and implements in that fresh session

# 4. When done, cleanup from main repo
cd "$(git rev-parse --show-toplevel)"
bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh cleanup

PR Review in Isolation

bash

# Create worktree from PR branch
bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh create pr-42-auth-fix origin/pr-branch

# CLAUDE STOPS HERE. Tells user to copy-paste the launch command into a new terminal.

# Cleanup after review
cd "$(git rev-parse --show-toplevel)"
bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh cleanup

Directory Structure

text

project-root/
├── .env                              # Source of truth
├── .github/
│   └── worktrees/                    # All worktrees live here
│       ├── feature-auth/
│       │   ├── .env -> ../../..      # Relative symlink to root .env
│       │   ├── src/
│       │   └── ...
│       └── feature-pipeline/
│           ├── .env -> ../../..      # Relative symlink to root .env
│           └── ...
└── .gitignore                        # Includes .github/worktrees

Troubleshooting

"Worktree already exists"

Switch to it instead:

bash

bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh switch <name>

"Cannot remove worktree: it is current"

Return to main repo first:

bash

cd "$(git rev-parse --show-toplevel)"
bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh cleanup

Symlink broken?

Recreate manually from the worktree directory:

bash

cd .github/worktrees/<name>
rm .env
# Compute relative path to project root .env
GIT_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
ln -s "$(python3 -c "import os; print(os.path.relpath('$GIT_ROOT/.env', '$(pwd)'))")" .env
ls -la .env  # Verify

Why a New Terminal?

Claude Code's CWD and statusline are set at launch. If you

cd

into a worktree from an existing session, the statusline stays wrong, and auto-compact causes Claude to revert to the main repo.

The script outputs a copy-paste command that:

```
cd
```
s to the worktree
Launches a new
```
claude
```
instance

This ensures correct statusline and stable context throughout the session.

git-worktree

NPX Install

Tags

SKILL.md Content

Git Worktree Manager

Quick Reference

CRITICAL: Always Use the Manager Script

CRITICAL: Create the Worktree, Then STOP

Project Conventions

Commands

`create <branch-name> [from-branch]`

`list`
or
`ls`

`switch <name>`
or
`go <name>`

`cleanup`
or
`clean`

Workflow Examples

Feature Development

PR Review in Isolation

Directory Structure

Troubleshooting

"Worktree already exists"

"Cannot remove worktree: it is current"

Symlink broken?

Why a New Terminal?

git-worktree

NPX Install

Tags

SKILL.md Content

Git Worktree Manager

Quick Reference

CRITICAL: Always Use the Manager Script

CRITICAL: Create the Worktree, Then STOP

Project Conventions

Commands

create <branch-name> [from-branch]

list or ls

switch <name> or go <name>

cleanup or clean

Workflow Examples

Feature Development

PR Review in Isolation

Directory Structure

Troubleshooting

"Worktree already exists"

"Cannot remove worktree: it is current"

Symlink broken?

Why a New Terminal?

`create <branch-name> [from-branch]`

`list`
or
`ls`

`switch <name>`
or
`go <name>`

`cleanup`
or
`clean`