Claude Code Worktree Hooks

Makes Claude Code worktrees work out of the box — symlinks node_modules, .env files, .vercel/, and Claude settings so you don't have to reinstall anything or deal with missing config.

What it does

When Claude Code creates a worktree, the hook automatically:

• Symlinks node_modules from the main repo (instant, no reinstall, no extra disk)
• Symlinks all .env.* files (root + nested packages) so secrets carry over
• Symlinks .vercel/ so Vercel env management works
• Symlinks .claude/settings.local.json so your personal Claude config carries over
• Runs proto install to install the right Node/pnpm versions
• Falls back to pnpm install only if no node_modules exist yet

Worktrees are stored in ~/.superset/worktrees/<project>/.

Setup

1. One-time machine setup

# Install jq if you don't have it
brew install jq

# Create the worktrees directory
mkdir -p ~/.superset/worktrees

2. Add to your repo

From the root of any repo you want worktree support in:

# Create the hooks directory
mkdir -p .claude/hooks

# Copy the hook scripts
cp path/to/claude-worktree-hooks/hooks/worktree-create.sh .claude/hooks/
cp path/to/claude-worktree-hooks/hooks/worktree-remove.sh .claude/hooks/

# Make them executable
chmod +x .claude/hooks/*.sh

3. Configure Claude Code

If your repo doesn't have .claude/settings.json yet:

cp path/to/claude-worktree-hooks/settings.json .claude/settings.json

If your repo already has .claude/settings.json, add the hooks key to it:

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/worktree-create.sh"
          }
        ]
      }
    ],
    "WorktreeRemove": [
      {
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/worktree-remove.sh"
          }
        ]
      }
    ]
  }
}

4. Commit

git add .claude/hooks/ .claude/settings.json
git commit -m "Add worktree hooks for Claude Code"

Once committed, every team member who pulls the repo gets worktree support automatically. No per-person setup needed beyond step 1.

How it works

When Claude Code spins up a worktree (e.g. for isolated feature work), it normally just does git worktree add — which gives you the code but none of the gitignored files your project needs to run (node_modules, .env files, .vercel config).

This hook runs after worktree creation and symlinks all of that from your main repo checkout. Since the worktree branches from HEAD, the dependencies are identical — symlinking is safe and instant.

If you later change dependencies in the worktree, just run pnpm install manually. It'll replace the symlink with a real node_modules.

Troubleshooting

"jq: command not found" — Run brew install jq.

Worktree has wrong Node/pnpm version — The hook runs proto install but if proto itself isn't installed, it skips this step. Install proto: curl -fsSL https://moonrepo.dev/install/proto.sh | bash

Missing .vercel/ in worktree — The hook only symlinks it if it exists in the main repo. Run vercel link in the main repo first, then new worktrees will pick it up.

node_modules not symlinked — Make sure you've run pnpm install in the main repo at least once. The hook symlinks from there.