---

name: worktree description: Manage git worktrees for parallel Claude Code sessions. Create, list, navigate, and remove worktrees with automatic port allocation for local native development. allowed-tools: Bash, Read, Write, Edit, Glob, Grep version: 1.3.0

Git Worktree Skill

Manage git worktrees for running parallel Claude Code sessions on the same repository. Each worktree gets its own isolated file state while sharing git history. All development runs natively — no Docker.

CRITICAL: Always Use Absolute Paths

All file operations and commands MUST use absolute paths to the target worktree. This allows working on any worktree from any session, regardless of the current working directory.

Rules

1. File tools (Read, Edit, Write, Glob, Grep): Always use the full absolute path (e.g., $HOME/worktrees/myapp-feature-auth/app/models/user.rb)
2. Git commands: Use git -C <worktree-path> instead of relying on cwd (e.g., git -C $HOME/worktrees/myapp-feature-auth status)
3. Tests: Pass the absolute path to your test runner (e.g., ~/.claude/scripts/native-test $HOME/worktrees/myapp-feature-auth/test/models/user_test.rb)
4. Bundle/Rails: Use bash -c 'cd <worktree-path> && bundle exec rails ...'

Examples

# GOOD - absolute paths work from anywhere
Read $HOME/worktrees/myapp-feature-auth/app/models/order.rb
git -C $HOME/worktrees/myapp-feature-auth diff master...HEAD

# BAD - relies on cwd, breaks cross-worktree usage
Read app/models/order.rb
git diff master...HEAD

Usage

/worktree <command> [options]

Commands:

• /worktree create <name> - Create a new worktree
• /worktree setup <path> - Run project setup on a worktree
• /worktree list - List all worktrees with their ports
• /worktree remove <name> - Remove a worktree
• /worktree status - Show current worktree info and port
• /worktree ports - Show port allocation registry

Core Concepts

What is a Worktree?

A git worktree is a linked copy of your repository at a different path. All worktrees share:

• Git history and commits
• Remote connections
• Branch references

Each worktree has its own:

• Working directory (file state)
• Checked out branch
• Staged changes

Why Use Worktrees?

1. Parallel Claude sessions - Work on multiple features simultaneously
2. Single session, multiple worktrees - Work across worktrees using absolute paths
3. Code isolation - Changes in one worktree don't affect others
4. Fast context switching - No need to stash/commit to switch tasks

---

Port Allocation System

Each worktree runs its own dev server on a unique port.

Port Registry

Ports are tracked in ~/.claude-worktree-ports:

# Format: worktree_path|port|project_name
/Users/you/code/myapp|3000|myapp
/Users/you/worktrees/myapp-feature-a|3001|myapp
/Users/you/worktrees/myapp-feature-b|3002|myapp

Port Allocation Rules

• Port 3000: Reserved for main checkout
• Ports 3001-3099: Available for worktrees
• Allocation is per-project (different projects can reuse ports)

Checking Current Port

cat $HOME/worktrees/myapp-<name>/.worktree-port 2>/dev/null || echo "3000 (main checkout)"

---

Commands Reference

Create Worktree

IMPORTANT: Always create worktrees in ~/worktrees/, NEVER in ~/code/. The ~/code/ directory is only for main checkouts.

/worktree create feature-auth

What happens:

1. Creates worktree at ~/worktrees/<repo>-<name>/
2. Allocates next available port
3. Creates .worktree-port file
4. Runs worktree-setup (copies config, installs deps)
5. Reports the assigned port

IMPORTANT: If you create a worktree manually (git worktree add), you MUST run worktree-setup afterwards.

With specific branch:

/worktree create feature-auth --branch user/o-1234-auth

With new branch:

/worktree create feature-auth --new-branch user/o-1234-auth

List Worktrees

/worktree list

Output:

Git Worktrees for myapp:

| Path | Branch | Port | Status |
|------|--------|------|--------|
| ~/code/myapp | master | 3000 | main |
| ~/worktrees/myapp-feature-a | user/o-1234-auth | 3001 | active |
| ~/worktrees/myapp-feature-b | user/o-1235-api | 3002 | active |

Remove Worktree

/worktree remove feature-auth

What happens:

1. Removes the worktree directory
2. Frees the port allocation
3. Cleans up git worktree reference

Show Status

/worktree status

Output:

Current Worktree: ~/worktrees/myapp-feature-a
Branch: user/o-1234-auth
Port: 3001
Web URL: http://localhost:3001

---

Post-Create Setup

ALWAYS run setup after creating a worktree. Use the setup script:

~/.claude/scripts/worktree-setup $HOME/worktrees/myapp-<name>

The setup script should be customized for your project. A typical Rails setup:

1. Copies config files from main checkout (credentials, environment configs, etc.)
2. Runs bundle install — Installs Ruby dependencies
3. Runs yarn install — Installs JavaScript dependencies
4. Writes .env.native — Port-aware environment variables
5. Prints server start command with correct port

Starting the Server

After setup, start with:

cd $HOME/worktrees/myapp-<name>
set -a && source .env.native && set +a && bundle exec rails server -p $PORT

Important: Work Within the Worktree

Never copy files from a worktree back to the main checkout. Each worktree is an isolated workspace. Always run tests and commands using absolute paths.

---

Implementation Details

Worktree Location

MANDATORY: All worktrees MUST be created in ~/worktrees/. Never create worktrees in ~/code/ or any other directory. The ~/code/ directory is reserved exclusively for the main checkout of each repository.

Path format: ~/worktrees/<repo-name>-<worktree-name>/

Example:

• Repo: myapp
• Worktree name: feature-auth
• Path: ~/worktrees/myapp-feature-auth/

WRONG: ~/code/myapp-feature-auth/ — never put worktrees in ~/code/

Port File

Each worktree has a .worktree-port file containing just the port number:

cat $HOME/worktrees/myapp-<name>/.worktree-port
# Output: 3001

This file is:

• Created by the worktree skill
• Read by your test runner and server start command
• Used to configure web server port and test DB isolation

Registry File

~/.claude-worktree-ports tracks all allocations:

cat ~/.claude-worktree-ports

# Format: path|port|project
/Users/you/code/myapp|3000|myapp
/Users/you/worktrees/myapp-feature-a|3001|myapp

---

Best Practices

1. One Task Per Worktree

Each worktree should represent one logical unit of work:

• A single feature
• A bug fix
• An exploration or spike

2. Clean Up After Merging

When a branch is merged, remove its worktree:

/worktree remove feature-auth

3. Isolated Test Databases

Each worktree automatically gets its own test database to avoid lock contention:

• Main checkout (port 3000) → myapp_test
• Worktree 1 (port 3001) → myapp_test_1
• Worktree 2 (port 3002) → myapp_test_2

This is handled by your test runner reading .worktree-port and setting TEST_ENV_NUMBER, which database.yml uses to suffix the test DB name. The development database is still shared across all worktrees.

The test database is auto-created on first test run — no extra setup needed.

---

Troubleshooting

"Worktree already exists"

# List existing worktrees
git worktree list

# Remove stale worktree reference
git worktree remove <path> --force

"Port already in use"

# Find what's using the port
lsof -i :3001

# Kill the process
kill -9 <PID>

# Or reallocate port
/worktree remove feature-a
/worktree create feature-a

"Branch already checked out"

Git doesn't allow the same branch in multiple worktrees:

# Check which worktree has the branch
git worktree list

# Either remove that worktree or use a different branch