Hooks

Hooks allow you to run commands automatically during the worktree lifecycle.

Available Hooks

Hook	When	Working Directory
pre_start	Before worktree creation	Origin repository
post_start	After worktree creation	New worktree
pre_clean	Before worktree removal	Current worktree
post_clean	After worktree removal	Main repository

Configuration

[hooks]
pre_start = ["echo 'Preparing worktree...'"]
post_start = [
  "pnpm install",
  "pnpm db:migrate"
]
pre_clean = ["git stash"]
post_clean = ["echo 'Cleanup complete'"]

Environment Variables

The following environment variables are available in all hook commands:

Variable	Description
VIBE_WORKTREE_PATH	Absolute path to the created worktree
VIBE_ORIGIN_PATH	Absolute path to the original repository

Example Usage

[hooks]
post_start = [
  "echo 'Worktree created at: $VIBE_WORKTREE_PATH'",
  "echo 'Origin repository: $VIBE_ORIGIN_PATH'"
]

Hook Output Behavior

vibe displays a real-time progress tree during hook execution:

✶ Setting up worktree feature/new-ui…
┗ ☒ Pre-start hooks
   ┗ ☒ npm install
     ☒ cargo build --release
  ⠋ Copying files
   ┗ ⠋ .env.local
     ☐ node_modules/

Output Handling

Situation	stdout	stderr
Progress display active	Suppressed	Always shown
Progress display inactive	Written to stderr	Always shown
Failed hooks	N/A	Always shown

Note

Progress display auto-disables in non-TTY environments (e.g., CI/CD), and hook output will be shown normally.

Hook Execution Order

For vibe start:

1. pre_start hooks run in origin repository
2. Worktree is created
3. Files/directories are copied
4. post_start hooks run in new worktree

For vibe clean:

1. pre_clean hooks run in current worktree
2. Worktree is removed
3. post_clean hooks run in main repository

Common Patterns

Node.js Project

[hooks]
post_start = [
  "pnpm install",
  "pnpm build"
]
pre_clean = ["git stash --include-untracked"]

Bun Project

[hooks]
post_start = [
  "bun install",
  "bun run build"
]
pre_clean = ["git stash --include-untracked"]

Database Migration

[hooks]
post_start = [
  "pnpm install",
  "pnpm db:migrate",
  "pnpm db:seed"
]

Docker Environment

[hooks]
post_start = [
  "docker-compose up -d",
  "sleep 5",
  "pnpm db:migrate"
]
pre_clean = ["docker-compose down"]

Skipping Hooks

You can skip hooks with the --no-hooks option:

vibe start feat/quick-fix --no-hooks

Claude Code Integration

vibe integrates with Claude Code’s WorktreeCreate and WorktreeRemove hooks. This replaces Claude Code’s default git worktree add behavior with vibe’s full workflow, including hooks, CoW file copying, and configuration.

Setup

Add the following to your Claude Code settings.json:

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "vibe start --claude-code-worktree-hook --quiet 2>/dev/null"
          }
        ]
      }
    ],
    "WorktreeRemove": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "vibe clean --claude-code-worktree-hook --force 2>/dev/null"
          }
        ]
      }
    ]
  }
}

How It Works

When Claude Code creates a worktree (via natural language, isolation: "worktree", or the /worktree command), vibe handles the full lifecycle:

WorktreeCreate:

1. Reads worktree name from stdin (Claude Code hook protocol)
2. Runs pre_start hooks in the origin repository
3. Creates the git worktree
4. Copies files/directories using CoW
5. Runs post_start hooks in the new worktree (e.g., pnpm install)
6. Outputs the worktree path to stdout for Claude Code

WorktreeRemove:

1. Reads worktree path from stdin (Claude Code hook protocol)
2. Runs pre_clean hooks in the worktree
3. Removes the git worktree
4. Runs post_clean hooks in the main repository

Benefits

Without this integration, Claude Code’s worktree creation only runs git worktree add. By using vibe’s hooks, you get:

• Automatic dependency installation (pnpm install, bun install, etc.)
• CoW file copying (.env, node_modules, etc.)
• Custom setup scripts (database migrations, Docker containers, etc.)
• Cleanup hooks on worktree removal