Claude Worktree Hooks

Auto-Setup for Claude Code Worktrees: Env Files, Ports, and Dependencies

Claude Code recently shipped a --worktree flag that creates isolated git worktrees for parallel AI sessions. It's great — spin up claude --worktree auth-refactor and you get a fresh copy of your repo on its own branch, completely isolated from your main working directory.

But here's the thing: a fresh worktree is _empty_. No .env files. No node_modules. No virtualenv. You have to set all that up before the agent can do anything useful.

We solved this with hooks. Here's how.

Quick start

1. Copy worktree-create.sh and worktree-remove.sh into your repo's scripts/ directory
2. Make them executable: chmod +x scripts/worktree-create.sh scripts/worktree-remove.sh
3. Customize the env files, directories, and dependency install commands in worktree-create.sh
4. Merge .claude/settings.json into your .claude/settings.json
5. Add /.claude/worktrees/ to your .gitignore
6. Run claude --worktree my-feature and watch the setup happen automatically

The problem

Say your project needs a few things before it can run:

Every time you spin up a new worktree, all of that is missing. You'd have to manually:

1. Copy .env from your main repo
2. Run npm install
3. Set up your virtualenv
4. Pick a port that doesn't collide with your other worktrees

If you're running 3 parallel Claude sessions, that's a lot of manual setup. And if you forget the .env, your agent will waste tokens debugging missing environment variables.

The solution: WorktreeCreate hook

Claude Code has a hook system that lets you run shell commands on specific events. The one we want is WorktreeCreate — it fires when claude --worktree is invoked, before the TUI renders.

From the docs: "If you configure a WorktreeCreate hook, it replaces the…