gh-jamesrochabrun-skills-all-skills/skills/git-worktrees/references/slash_command_template.md

Custom /worktree Slash Command Template

Create a custom /worktree command for Claude Code to streamline worktree creation.

---

Overview

This template allows you to create a slash command that:

1. Creates a new Git worktree
2. Provides setup instructions
3. Offers to continue the conversation in the new worktree

Usage after setup:

/worktree feature-new-api

Claude will create the worktree and guide you through the next steps.

---

Setup Instructions

Step 1: Create Command File

Create a new file in your Claude Code commands directory:

# For project-specific command
mkdir -p .claude/commands
touch .claude/commands/worktree.md

# For global command (all projects)
mkdir -p ~/.claude/commands
touch ~/.claude/commands/worktree.md

---

Step 2: Add Command Content

Copy this template into worktree.md:

---
description: Create a new Git worktree for parallel development with Claude Code
---

# Create Git Worktree

{{#if (not args.0)}}
**Usage:** `/worktree <branch-name> [base-branch]`

**Examples:**
- `/worktree feature-api` - Create worktree from main
- `/worktree feature-ui develop` - Create worktree from develop
- `/worktree hotfix-urgent` - Create hotfix worktree

**What this does:**
1. Creates a new Git worktree
2. Sets up the directory structure
3. Provides setup instructions

{{else}}

## Creating Worktree: {{args.0}}

Let me create a new Git worktree for parallel development.

**Branch name:** `{{args.0}}`
{{#if args.1}}
**Base branch:** `{{args.1}}`
{{else}}
**Base branch:** `main` (default)
{{/if}}

### Step 1: Create the Worktree

Run this command in your terminal:

\`\`\`bash
scripts/create_worktree.sh
\`\`\`

When prompted:
- Feature name: **{{args.0}}**
{{#if args.1}}
- Base branch: **{{args.1}}**
{{else}}
- Base branch: **main** (or press Enter for default)
{{/if}}

The script will create the worktree in a sibling directory.

### Step 2: Open in New Claude Code Session

After the script completes:

1. Note the worktree path (shown by the script)
2. Open a new Claude Code window
3. Navigate to the worktree directory
4. **Important:** Run `/init` to orient Claude

### Step 3: Start Development

Once in the new worktree with Claude initialized, I can help you:
- Implement the feature
- Write tests
- Create documentation
- Review code

### Alternative: Manual Creation

If you prefer manual setup:

\`\`\`bash
# Get repository root
REPO_ROOT=$(git rev-parse --show-toplevel)
REPO_NAME=$(basename "$REPO_ROOT")

# Create worktree
{{#if args.1}}
git worktree add ../$REPO_NAME-{{args.0}} -b {{args.0}} {{args.1}}
{{else}}
git worktree add ../$REPO_NAME-{{args.0}} -b {{args.0}} main
{{/if}}

# Open in editor
cd ../$REPO_NAME-{{args.0}}
code .
\`\`\`

### Managing Worktrees

**List all worktrees:**
\`\`\`bash
scripts/list_worktrees.sh
\`\`\`

**Sync with main:**
\`\`\`bash
scripts/sync_worktree.sh
\`\`\`

**Clean up when done:**
\`\`\`bash
scripts/cleanup_worktrees.sh
\`\`\`

---

**Would you like me to help with anything else before you switch to the new worktree?**

{{/if}}

---

Step 3: Test the Command

# In Claude Code, type:
/worktree feature-new-api

# Or with custom base branch:
/worktree feature-ui develop

---

Advanced Template (With Automatic Creation)

For users who want Claude to automatically create the worktree (not just show instructions):

---
description: Create and set up a new Git worktree for parallel development
---

# Create Git Worktree: {{args.0}}

{{#if (not args.0)}}
**Error:** Branch name required

**Usage:** `/worktree <branch-name> [base-branch]`

**Examples:**
- `/worktree feature-api`
- `/worktree feature-ui develop`
{{else}}

I'll create a new Git worktree for `{{args.0}}`.

## Creating Worktree

\`\`\`bash
#!/bin/bash

# Configuration
BRANCH_NAME="{{args.0}}"
{{#if args.1}}
BASE_BRANCH="{{args.1}}"
{{else}}
BASE_BRANCH="main"
{{/if}}

# Get repository info
REPO_ROOT=$(git rev-parse --show-toplevel)
REPO_NAME=$(basename "$REPO_ROOT")
WORKTREE_DIR="$(dirname "$REPO_ROOT")/${REPO_NAME}-${BRANCH_NAME}"

# Validate
if [ ! -d "$REPO_ROOT/.git" ]; then
    echo "Error: Not in a git repository"
    exit 1
fi

# Check if branch exists
if git show-ref --verify --quiet "refs/heads/$BRANCH_NAME"; then
    echo "⚠ Branch $BRANCH_NAME already exists"
    echo "Using existing branch..."
    git worktree add "$WORKTREE_DIR" "$BRANCH_NAME"
else
    echo "✓ Creating new branch from $BASE_BRANCH..."
    git worktree add -b "$BRANCH_NAME" "$WORKTREE_DIR" "$BASE_BRANCH"
fi

echo ""
echo "✓ Worktree created successfully!"
echo ""
echo "Next steps:"
echo "1. Open new Claude Code window"
echo "2. Navigate to: $WORKTREE_DIR"
echo "3. Run: /init"
echo "4. Start development!"
\`\`\`

Run the script above to create the worktree.

## What's Next?

After creating the worktree:

1. **Open in new window:** \`code {{WORKTREE_PATH}}\`
2. **Run /init:** To orient Claude in the new environment
3. **Start coding:** I'll be ready to help with {{args.0}}!

## Useful Commands

**View all worktrees:**
\`\`\`bash
git worktree list
\`\`\`

**When done, merge back:**
\`\`\`bash
git checkout main
git merge {{args.0}}
\`\`\`

**Remove worktree:**
\`\`\`bash
git worktree remove ../{{REPO_NAME}}-{{args.0}}
git branch -d {{args.0}}
\`\`\`

{{/if}}

---

Usage Examples

Example 1: Simple Feature

User: /worktree feature-authentication

Claude's response:

• Shows worktree creation instructions
• Explains next steps
• Offers to continue in new worktree

---

Example 2: Custom Base Branch

User: /worktree feature-dashboard develop

Claude's response:

• Creates worktree from develop instead of main
• Adjusts instructions accordingly

---

Example 3: List Current Worktrees

User: /worktree

Claude's response:

• Shows usage instructions
• Lists example commands
• Explains what the command does

---

Customization Options

Add Project-Specific Logic

Modify the template to include project-specific setup:

### Step 4: Project Setup

After creating the worktree, run:

\`\`\`bash
cd {{WORKTREE_PATH}}

# Install dependencies
npm install

# Run database migrations
npm run migrate

# Start dev server
npm run dev
\`\`\`

---

Add Team Conventions

Include your team's specific workflow:

### Team Workflow

1. Create worktree with `/worktree <feature-name>`
2. Update Jira ticket status to "In Progress"
3. Create draft PR: `gh pr create --draft`
4. Develop feature
5. Request review when ready

---

Add Validation

Enforce naming conventions:

{{#if (not (match args.0 "^(feature|hotfix|refactor|experiment)-"))}}
**Error:** Branch name must start with feature-, hotfix-, refactor-, or experiment-

**Valid examples:**
- feature-user-auth
- hotfix-login-bug
- refactor-api-layer
- experiment-new-db
{{/if}}

---

Troubleshooting

Command Not Found

Problem: /worktree command doesn't appear

Solution:

1. Check file location: .claude/commands/worktree.md
2. Restart Claude Code
3. Verify file has correct frontmatter (YAML header with description)

---

Script Path Issues

Problem: Scripts not found

Solution:

• Use absolute paths: <skill-path>/scripts/create_worktree.sh
• Or add scripts to PATH
• Or check scripts are in correct location

---

Template Variables Not Working

Problem: {{args.0}} showing as literal text

Solution:

• Ensure proper template syntax
• Check Claude Code version (templates require recent version)
• Verify YAML frontmatter is correct

---

Complete Example

Here's a fully working example you can copy directly:

File: .claude/commands/worktree.md

---
description: Create a Git worktree for parallel Claude Code development
---

# Git Worktree Manager

{{#if args.0}}

## Creating Worktree: {{args.0}}

I'll help you set up a new Git worktree for parallel development.

### Quick Setup

Run this command:

\`\`\`bash
scripts/create_worktree.sh
\`\`\`

When prompted, enter: **{{args.0}}**

### Next Steps

1. ✓ Script will create the worktree
2. Open new Claude Code window
3. Navigate to the new worktree directory
4. Run \`/init\` to orient me
5. Start development on {{args.0}}!

### Manual Alternative

\`\`\`bash
# Create worktree
git worktree add ../$(basename $(git rev-parse --show-toplevel))-{{args.0}} -b {{args.0}}

# Open it
cd ../$(basename $(git rev-parse --show-toplevel))-{{args.0}}
code .
\`\`\`

**Ready to switch?** See you in the new worktree!

{{else}}

## Git Worktree Command

Create a new worktree for parallel development.

**Usage:**
\`\`\`
/worktree <branch-name>
\`\`\`

**Examples:**
\`\`\`
/worktree feature-api
/worktree refactor-auth
/worktree hotfix-urgent
\`\`\`

**What it does:**
- Creates a new Git worktree in a sibling directory
- Sets up the branch
- Provides setup instructions

**Manage worktrees:**
- List all: \`scripts/list_worktrees.sh\`
- Sync with main: \`scripts/sync_worktree.sh\`
- Clean up: \`scripts/cleanup_worktrees.sh\`

{{/if}}

---

Benefits of Custom Command

Faster workflow:

• Type /worktree feature-name instead of manual commands
• Consistent setup every time
• Team standardization

Better documentation:

• Built-in help
• Examples always available
• Team-specific instructions

Claude integration:

• Seamless handoff to new worktree
• Context preservation
• Guided workflow

---

Summary

1. Create worktree.md in .claude/commands/
2. Copy template
3. Customize for your team
4. Use /worktree <branch-name> in Claude Code
5. Enjoy streamlined parallel development!

Next level: Share the command template with your team for consistent workflows.