Skip to main content

Worktree Gate

PreToolUse:Edit:Write:NotebookEditworktreeEnabled by default

Blocks file edits on main and nudges Claude to create a descriptively-named worktree before touching any code.

Why use this

A good branch name requires knowing the task. By the time the first edit fires, Claude has that context — so the gate enforces isolation exactly when there's enough information to name the branch well, with no later rename step.

Lifecycle

Where in the Claude Code session this hook fires.

SessionStart
→
PreToolUse
→
PostToolUse
→
Stop
→
Notification
Pre Tool Use

Fires before each tool call. Can block or modify the action.

Fires only when the tool matches: EditWriteNotebookEdit

How it works

Intercepts Edit, Write, and NotebookEdit tool calls when running on the default branch outside a worktree. Blocks the call and asks Claude to create a named branch via a worktree. Escape hatch: `.claude/skip-worktree` bypasses the gate for two hours for deliberate main-branch edits like CHANGELOGs or version bumps.

settings.json

What the hook configuration looks like in ~/.claude/settings.json after install.

~/.claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "node ~/.claude/plugins/tonone-ai/tonone/tonone-worktree-gate.js"
          }
        ]
      },
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "node ~/.claude/plugins/tonone-ai/tonone/tonone-worktree-gate.js"
          }
        ]
      },
      {
        "matcher": "NotebookEdit",
        "hooks": [
          {
            "type": "command",
            "command": "node ~/.claude/plugins/tonone-ai/tonone/tonone-worktree-gate.js"
          }
        ]
      }
    ]
  }
}

Install

This hook

Install Worktree Gate

1. Add to marketplace

$ claude plugin marketplace add tonone-ai/tonone

2. Install this hook

$ claude plugin install worktree-gate@tonone-ai

More worktree hooks

All hooks
Stop
On

Worktree Close

Prints a /ship prompt at turn end when the current worktree has unshipped changes, so nothing gets forgotten.

tonone-worktree-close.js

Ready to use Worktree Gate?

Get StartedBack to Hooks