Block Worktree Creation From a Detached HEAD State

A worktree created from a detached HEAD has no branch name tying it back to anything reviewable — any work done there is one `git gc` away from being unreachable. This requires the source to be a named branch.

Worktree & Git Safety Event: WorktreeCreate Claude Code Open source · Free

1. Save this as the hook script

#!/usr/bin/env python3
"""WorktreeCreate hook — blocks creation from a detached HEAD state."""
import json, sys

data = json.load(sys.stdin)

if data.get("detached"):
    print("BLOCKED: worktree requested from a detached HEAD — work done "
          "there has no branch name tying it back to anything reviewable.", file=sys.stderr)
    sys.exit(1)

sys.exit(0)

Save to a path inside your project, e.g. .claude/hooks/block-worktree-from-detached-head.sh, then chmod +x it.

2. Wire it into .claude/settings.json

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {"type": "command", "command": "python3 .claude/hooks/block-worktree-from-detached-head.py"}
        ]
      }
    ]
  }
}

Before you use this

A hook runs with your local shell's permissions — review the script above before adding it, the same way you'd review any script you didn't write yourself. See our guide on hook security risks for the specific CVEs this category of feature has already produced.

Related hooks

Block Worktree Removal With Uncommitted or Unpushed Changes
Blocks removing a worktree if it has uncommitted changes or commits not yet pushed anywhe…
Enforce a Mandatory Ticket-ID Prefix on Worktree Names
Blocks worktree creation unless the requested name starts with a recognized ticket-ID pat…
Log Every Worktree Created, With Parent Branch and Requester
A logging-only companion hook that records every worktree creation without blocking any o…
Require a Clean Working Tree Before Creating a Worktree
Blocks creating a new worktree if the parent repo's working tree has uncommitted changes.
← All hooks
FEEDBACK