フック

フックを使用すると、Worktreeのライフサイクル中にコマンドを自動的に実行できます。

利用可能なフック

フック	実行タイミング	作業ディレクトリ
`pre_start`	Worktree作成後	元リポジトリ
`post_start`	Worktree作成後	新しいWorktree
`pre_clean`	Worktree削除前	現在のWorktree
`post_clean`	Worktree削除後	メインリポジトリ

設定

[hooks]
pre_start = ["echo 'Worktreeを準備中...'"]
post_start = [
  "pnpm install",
  "pnpm db:migrate"
]
pre_clean = ["git stash"]
post_clean = ["echo 'クリーンアップ完了'"]

環境変数

すべてのフックコマンドで以下の環境変数が利用可能です：

変数	説明
`VIBE_WORKTREE_PATH`	作成されたWorktreeの絶対パス
`VIBE_ORIGIN_PATH`	元リポジトリの絶対パス

使用例

[hooks]
post_start = [
  "echo 'Worktree作成先: $VIBE_WORKTREE_PATH'",
  "echo '元リポジトリ: $VIBE_ORIGIN_PATH'"
]

フック実行時の出力動作

vibeはフック実行中にリアルタイム進捗ツリーを表示します：

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

マーカーの意味

マーカー	意味
`⠋`	待機中または実行中（開始するとスピナーが回ります）
`☒`	正常に完了
`✗`	失敗（赤）。理由が `(failed: …)` として続きます
`⊘`	中断（淡色）。実行終了時点で未完了のまま

フェーズ行（外側の ┗）自体は結果を持たず、配下のタスクを集約して表示します。未完了のタスクが1つでもあれば ⊘、そうでなく失敗したタスクがあれば ✗ と (failed: N task(s) failed)、いずれでもなければ ☒ になります。

出力の処理

状況	標準出力	標準エラー出力
進捗表示が有効	抑制される	常に表示
進捗表示が無効	標準エラーに出力	常に表示
失敗したフック	N/A	常に表示

フック実行順序

vibe startの場合：

Worktreeが作成される
[submodules] configs = [...]の場合、指定されたサブモジュールが初期化される
各サブモジュールの信頼済みpre_start、copyルール、post_startがサブモジュールルート基準で実行される
親のpre_startフックが元リポジトリで実行
親のファイル/ディレクトリがコピーされる
親のpost_startフックが新しいWorktreeで実行

vibe cleanの場合：

pre_cleanフックが現在のWorktreeで実行
Worktreeが削除される
post_cleanフックがメインリポジトリで実行

フック失敗時の動作

フックが非ゼロで終了した場合、それはエラーではなく警告です。vibeは Warning: Hook "..." failed: ...を表示し、終了ステータスは0のままです。変わるのはディレクトリ移動が行われるかどうかで、それはフックがライフサイクルのどこに位置するかで決まります。

フック	失敗時の動作
`pre_start`	ゲートとして機能：コピーと`post_start`はスキップされ、元のディレクトリに留まります
`post_start`	警告のみ：Worktreeのセットアップは完了しているため、vibeはそのままWorktreeへ移動します
`pre_clean`	ゲートとして機能：Worktreeは削除されず、そのWorktreeに留まります
`post_clean`	警告のみ：Worktreeは既に削除済みのため、vibeはそのままメインリポジトリへ移動します

これによりpre_startとpre_cleanを事前条件チェックとして利用できます。たとえばシークレットVaultへの到達性を検証するpre_startは、セットアップできなかったWorktreeへ入るのを防ぎます。

ゲートされたvibe startでもWorktreeディレクトリ自体はディスク上に残り、抑止されるのは移動だけです。同じブランチでvibe startを再実行すると、そのWorktreeが見つかり移動するか確認されますが、その経路でもゲートは再度実行されます。したがってpre_startが依然として失敗する場合は、やはり中に入れません。原因を修正すれば、再実行時にゲートされた実行でスキップされたコピーとpost_startも実行されるため、最終的に入るWorktreeは完全にセットアップされた状態になります。

Claude Codeフックモード

vibe start --claude-code-worktree-hookには留まるべきシェルが存在しないため、 pre_startのゲートをディレクトリ移動の抑止として表現できません。このモードは契約を維持し（Worktreeパスをstdoutへ出力し、終了ステータスは0）、代わりにゲートが作動したことを機械可読な固定の1行としてstderrへ出力します。

vibe: pre_start hook failed; worktree is not provisioned

この行は1回の実行につき最大1回、装飾なし（カラーコードなし）で出力され、pre_startのゲート時のみ現れます。post_startの失敗では通常のWarning: Hook "..." failed: ...が出るだけです。この行は、受け取ったパスがコピーとpost_startをスキップしたWorktreeを指していることを示すシグナルとして扱ってください。

2点の注意事項があります。

後述のセットアップ例はコマンドの末尾が2>/dev/nullになっており、 stderrを、したがってこのシグナルも破棄します。ゲートを観測したい場合はこのリダイレクトを外してください。
このシグナルはWorktreeを作成する実行に付随します。すでにWorktreeが存在するブランチに対してフックを再度呼び出すと、フックを再実行せずに既存のパスを返すため、 2回目の呼び出しではシグナルは出力されません。

よくあるパターン

Node.jsプロジェクト

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

Bunプロジェクト

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

データベースマイグレーション

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

Docker環境

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

Gitサブモジュール

直接サブモジュールに独自のsetupファイルやフックがある場合は、ファーストクラスのサブモジュール設定を使用してください：

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

これは新しいWorktree内でgit submodule update --init -- libs/fooを実行し、その後libs/foo/.vibe.tomlを通常のtrust store経由で読み込みます。サブモジュールのcopyルールとフックはlibs/foo基準で解決され、親リポジトリのpre_startフックより前に実行されます。

フックのスキップ

--no-hooksオプションでフックをスキップできます：

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

Claude Code連携

vibeはClaude CodeのWorktreeCreateおよびWorktreeRemoveフックと連携できます。これにより、Claude Codeのデフォルトのgit worktree add動作をvibeのフルワークフロー（フック、CoWファイルコピー、設定を含む）に置き換えます。

セットアップ

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"
          }
        ]
      }
    ]
  }
}

動作の仕組み

Claude CodeがWorktreeを作成する場合（自然言語、isolation: "worktree"、または/worktreeコマンド経由）、vibeがフルライフサイクルを管理します：

WorktreeCreate:

stdinからWorktree名を読み取り（Claude Codeフックプロトコル）
git Worktreeを作成
[submodules] configs = [...]の場合、指定されたサブモジュールを初期化し、信頼済みsetupを実行
元リポジトリで親のpre_startフックを実行
CoWを使用して親のファイル/ディレクトリをコピー
新しいWorktreeで親のpost_startフックを実行（例：pnpm install）
Claude Code向けにWorktreeパスをstdoutに出力

WorktreeRemove:

stdinからWorktreeパスを読み取り（Claude Codeフックプロトコル）
Worktreeでpre_cleanフックを実行
git Worktreeを削除
メインリポジトリでpost_cleanフックを実行

メリット

この連携がない場合、Claude CodeのWorktree作成はgit worktree addのみを実行します。vibeのフックを使用することで、以下が自動的に行われます：

依存関係の自動インストール（pnpm install、bun installなど）
CoWファイルコピー（.env、node_modulesなど）
カスタムセットアップスクリプト（データベースマイグレーション、Dockerコンテナなど）
Worktree削除時のクリーンアップフック