Hooks

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

Available Hooks

Hook	When	Working Directory
pre_start	After 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. Worktree is created
2. Listed submodules are initialized when [submodules] configs = [...]
3. Each listed submodule’s trusted pre_start, copy rules, and post_start run from that submodule root
4. Parent pre_start hooks run in origin repository
5. Parent files/directories are copied
6. Parent 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"]

Git Submodules

Use first-class submodule configs when a direct submodule has its own setup files or hooks:

[submodules]
configs = ["libs/foo"]

This runs git submodule update --init -- libs/foo in the new worktree, then loads libs/foo/.vibe.toml through the normal trust store. The submodule’s copy rules and hooks resolve paths from libs/foo, and they run before the parent repository’s pre_start hooks.

Note

Use a hook instead when you need custom submodule behavior, such as recursive updates, filtered updates, or intentionally ignoring failures.

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. Creates the git worktree
3. Initializes listed submodules and runs their trusted setup when [submodules] configs = [...]
4. Runs parent pre_start hooks in the origin repository
5. Copies parent files/directories using CoW
6. Runs parent post_start hooks in the new worktree (e.g., pnpm install)
7. 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