/worktree

/worktree Command

Create a new git worktree for a Laravel project served by Laravel Valet. Uses generated scripts/setup.sh for environment setup instead of inline steps.

Arguments

• branch-name (optional): The name for the new branch. If not provided, prompt using AskUserQuestion.

Pre-flight Checks

1. Verify not already in a worktree:

   git rev-parse --show-toplevel 2>/dev/null
   

   If the path contains .worktrees/, warn the user they're already in a worktree and ask if they want to continue from the main project directory.

2. Check for existing worktrees:

   git worktree list
   

   If multiple worktrees exist, inform the user.

Workflow

Step 1: Get Branch Name

If $ARGUMENTS is provided, use it directly. Otherwise, use AskUserQuestion:

header: "Branch Name"
question: "What branch name do you want for this worktree?"

Sanitize the branch name:

SANITIZED_BRANCH=$(echo "$BRANCH" | tr '/' '-' | tr ' ' '-' | tr '[:upper:]' '[:lower:]')

Step 2: Detect Project Name

Use the helper script:

PROJECT=$(${CLAUDE_PLUGIN_ROOT}/scripts/detect-project-name.sh)

Step 3: Detect Base Branch

BASE_BRANCH=$(git config init.defaultBranch 2>/dev/null || echo "main")
# Verify it exists
git show-ref --verify --quiet refs/heads/$BASE_BRANCH || BASE_BRANCH="master"

Step 4: Check for Scripts

if [ ! -f scripts/setup.sh ]; then
    echo "scripts/setup.sh not found. Generating scripts first..."
fi

If scripts/setup.sh is missing, inform the user and trigger /scripts generation before proceeding. Do not continue without the scripts.

Step 5: Create Worktree

git worktree add .worktrees/$SANITIZED_BRANCH -b $BRANCH $BASE_BRANCH

Step 6: Copy Scripts

cp -r scripts/ .worktrees/$SANITIZED_BRANCH/scripts/

Step 6.5: Copy Dependencies

Copy vendor/ and node_modules/ from the main project before running setup. Since the worktree shares the same composer.lock and package-lock.json, these directories are identical — turning composer install / npm install into fast verification steps instead of full installs.

echo "Pre-copying dependencies from main project..."
cp -R vendor/ .worktrees/$SANITIZED_BRANCH/vendor/ 2>/dev/null && echo "vendor/ copied" || echo "No vendor/ to copy"
cp -R node_modules/ .worktrees/$SANITIZED_BRANCH/node_modules/ 2>/dev/null && echo "node_modules/ copied" || echo "No node_modules/ to copy"

Why here and not in setup.sh? setup.sh is also used by Codex/Conductor environments where there's no parent project to copy from. The worktree command always has a parent project available.

Step 7: Run setup.sh

This single command replaces the old inline steps (Valet link, .env config, DB creation, dependencies, migrations, etc.):

cd .worktrees/$SANITIZED_BRANCH
WT_WORKSPACE_NAME=$SANITIZED_BRANCH \
WT_ROOT_PATH=$(cd ../.. && pwd) \
bash scripts/setup.sh

Step 8: Fix Vite Configuration (if needed)

Check if vite.config.js or vite.config.ts has CORS settings. If missing, add:

server: {
    host: 'localhost',
    cors: true,
}

Only modify if these settings are missing.

Step 9: Setup Warp Launch Configuration

Skip if ~/.warp/ doesn't exist.

mkdir -p ~/.warp/launch_configurations

WORKTREE_PATH="$(pwd)"
sed -e "s|{{WORKTREE_PATH}}|$WORKTREE_PATH|g" \
    -e "s|{{WORKTREE_NAME}}|$SANITIZED_BRANCH|g" \
    ${CLAUDE_PLUGIN_ROOT}/templates/laravel-worktree.yaml \
    > ~/.warp/launch_configurations/laravel-worktree.yaml

Step 10: Display Summary

Output a summary table:

## Worktree Created Successfully

| Item | Value |
|------|-------|
| Branch | $BRANCH |
| Directory | .worktrees/$SANITIZED_BRANCH/ |
| URL | http://$PROJECT-$SANITIZED_BRANCH.test |
| Database | ${PROJECT}_${SANITIZED_BRANCH} |

### Next Steps

1. **Open Warp layout:** Press `Cmd+Ctrl+L` and select "Laravel Worktree"
2. **Start services:** Run `bash scripts/run.sh` (or use the Warp layout)
3. **Open in browser:** Run `browse` or visit the URL above

### Useful Commands

| Command | Description |
|---------|-------------|
| `browse` | Open project in browser |
| `opendb` | Open database in GUI |
| `p` | Run tests |
| `a` | php artisan shortcut |
| `bash scripts/run.sh` | Start all dev services |

**IMPORTANT:** All subsequent work must use the worktree directory:
`.worktrees/$SANITIZED_BRANCH/`

Error Handling

• If worktree already exists, offer to enter it instead of creating
• If Valet link fails, suggest running valet install
• If database creation fails, check if the DB server is running
• If branch already exists, offer to use existing branch
• If scripts/setup.sh fails, show the error output and suggest checking references/troubleshooting.md