worktrunk

Worktrunk

Git worktree を管理する CLI ツール、Worktrunk の使い方を案内します。

利用可能なドキュメント

参照ファイルは worktrunk.dev のドキュメントから同期されています。

• reference/config.md：ユーザーとプロジェクトの設定（LLM、フック、コマンドのデフォルト）
• reference/hook.md：フックの種類、タイミング、実行順序
• reference/switch.md、merge.md、list.md など：コマンドのドキュメント
• reference/extending.md：エイリアス、複数ステップのパイプライン、カスタムサブコマンド、テンプレート展開に関する注意点（2 パスの {% raw %} 遅延、for-each レシピ）
• reference/llm-commits.md：LLM によるコミットメッセージの生成
• reference/tips-patterns.md：実用的なレシピ — エイリアス、ブランチごとの変数、worktree ごとの開発サーバー、エージェントの並列実行パターン
• reference/shell-integration.md：シェル統合のデバッグ
• reference/troubleshooting.md：LLM とフックに関するトラブルシューティング（Claude 固有）

コマンド固有のオプションは、wt <command> --help を実行してください。設定については、以下のワークフローに従ってください。

コマンドが操作する worktree

wt は作業ディレクトリからリポジトリを特定し、コマンドの引数からworktreeを特定します。すべてのケースに当てはまるルールは 2 つです。

1. ブランチを指定するコマンドでは、そのブランチが worktree も指定します。 worktree はブランチ名で指定するため、wt switch <branch>、wt remove <branch>、wt step diff --branch <branch>、wt config state marker set --branch <branch> は、どの worktree から実行しても、そのブランチの worktree を操作します。このような引数には、ブランチ名で指定できないケース（同じブランチの 2 つ目のチェックアウトや、detached worktree）に備えて、worktree 自体のパスも指定できます（ただし、marker はブランチ名をキーに状態を管理するため、detached worktree は引き続き拒否します）。
2. -C <path> は作業ディレクトリを移動しますが、worktree の選択は変えません。 リポジトリの特定に問題がある場合に使います。たとえば、別のリポジトリを対象にする場合、現在の worktree を操作し、ブランチ引数を取らないコマンド（wt merge、wt step rebase|squash|push — これらの [TARGET] はマージ対象であり、worktree ではありません）を実行する場合、またはホストによって作業ディレクトリが別の場所に固定されているエージェントフックなど、呼び出し元の作業ディレクトリがリポジトリ内にない場合です。

ブランチ引数と -C を併用すると、同じ worktree を二重に指定することになります。beta もあるリポジトリの alpha worktree 内から実行する場合：

wt step diff --branch beta                    # ✓ the branch argument selects the worktree
wt -C ../repo.beta step diff --branch beta    # ✗ says beta twice

wt switch --create beta                       # ✓ --base already defaults to the default branch
wt -C ../repo switch --create beta            # ✗ -C adds nothing; you are already in that repo

2 種類の設定

Worktrunk では、スコープと権限モデルの異なる 2 つの設定ファイルを使います。

ユーザー設定（~/.config/worktrunk/config.toml、git にチェックインされません）には、LLM 統合、worktree パスのテンプレート、コマンド設定、ユーザーフックなど、個人の設定を保存します。慎重に扱ってください。変更を提案して、編集前に同意を得てください。ユーザーに代わってツールをインストールせず、既存のファイル構造やコメントを維持してください。詳しくは reference/config.md を参照してください。

プロジェクト設定（<repo>/.config/wt.toml、git にチェックインされます）には、worktree のライフサイクル（開始前、マージ前など）に関するフックといった、チーム全体の自動化を保存します。積極的に編集してかまいません。変更はバージョン管理され、git で元に戻せます。各フックの目的をコメントで説明し、破壊的なコマンド（rm -rf、DROP TABLE）、シェルにパイプするネットワーク取得コマンド、または sudo を追加する前にユーザーに警告してください。詳しくは reference/hook.md を参照してください。

リクエストによっては両方に関わるものもあります。コミットメッセージの生成はユーザー設定、チームの品質チェックはプロジェクト設定です。

主なワークフロー

コミットメッセージ生成の設定（ユーザー設定）

インストール済みのツールを確認します（which claude codex opencode llm aichat）。どれもない場合は Claude Code を推奨してください。選んだツールに対応するコマンドを reference/llm-commits.md からそのまま取得し、[commit.generation] の変更を提案したうえで、承認後に適用します（設定ファイルがない場合は先に wt config create を実行します）。確認するには、wt step commit --dry-run を実行します。これによりプロンプトが生成され、LLM が実行され、コミットせずにメッセージが出力されます。

プロジェクトフックの設定

コマンドを実行するタイミングと、処理をブロックしてよいかどうかに基づいてフックの種類を選択します。reference/hook.md では、10 種類すべて（5 つのイベント × 実行前／実行後）のタイミングと一般的な用途を説明しています。

プロジェクト自体（package.json のスクリプト、Cargo.toml、pyproject.toml）からコマンドを導き出し、追加する前に実行できることを確認してください。

新しいフックを既存のフックの完了後に実行する必要がある場合は、エントリーをパイプラインに変更します。名前付きテーブル内の独立したコマンドは並行して実行されます。

# Pipeline: install completes before migrate starts
[[pre-start]]
install = "npm install"

[[pre-start]]
migrate = "npm run db:migrate"

# Concurrent: independent commands in one table
[pre-start]
install = "npm install"
env = "cp .env.example .env"

wt switch --create test-hooks でテストします。

よくあるタスクのリファレンス

ユーザー設定のタスク

• コミットメッセージの生成を設定する → reference/llm-commits.md
• ワークツリーのパスをカスタマイズする → reference/config.md#worktree-path-template
• カスタムコミットテンプレートを設定する → reference/llm-commits.md#prompt-templates
• コマンドのデフォルトを設定する → reference/config.md#command-config
• 個人用フックを設定する → reference/config.md#user-hooks

プロジェクト設定のタスク

• 新しいプロジェクト用にフックを設定する → reference/hook.md
• 既存の設定にフックを追加する → reference/hook.md#hook-forms
• テンプレート変数を使用する → reference/hook.md#template-variables
• 開発サーバーの URL をリストに追加する → reference/config.md#dev-server-url

エイリアスとマルチワークツリーのタスク

• wt エイリアスを作成する → reference/extending.md#aliases
• すべてのワークツリーでコマンドを実行する → reference/step.md#wt-step-for-each
• すべてのワークツリーを上流ブランチにリベースする（up-style） → reference/extending.md#recipe-rebase-every-worktree-onto-its-upstream
• ネストした wt コマンドにテンプレートを渡す → reference/extending.md#nesting-templates

主なコマンド

# View all configuration
wt config show

# Create initial user config (LLM/commit setup: see reference/llm-commits.md)
wt config create

# Full config reference (subcommands, templates, env vars)
wt config --help

非対話型セッションでのフック承認

Worktrunk は、ユーザーが明示的に承認するまで、プロジェクトのフックやエイリアスを実行しません。.config/wt.toml 内のコマンドは、ユーザーが直前にクローンした可能性のあるリポジトリに含まれる任意のシェルコードです。そのため、初回実行時に Worktrunk は各コマンドを表示し、ユーザーの承認を待ちます。信頼されていない .config/wt.toml が何も知らせずにコードを実行することはありません。承認はプロジェクトごとに ~/.config/worktrunk/approvals.toml へ保存され、コマンドテンプレートが変更されるたびに再度確認されるため、承認済みのフックを別のコマンドに差し替えることはできません。

wt merge、wt switch、またはフックを起動するその他のコマンドを実行するエージェントには、次のようなエラーが表示されます。

▲ cargo-difftest needs approval to execute 1 command:
○ post-merge install:
  cargo install --path .
✗ Cannot prompt for approval in non-interactive environment
↳ To skip prompts in CI/CD, add --yes; to pre-approve commands, run wt config approvals add --yes

解決するには、ユーザー自身が信頼するかどうかを判断する必要があります。

• wt config approvals add — ユーザーが各コマンドを確認してから ~/.config/worktrunk/approvals.toml に保存する対話型プロンプトです。プロジェクトごとに一度実行します。コマンドテンプレートが変更されるか、プロジェクトが移動するまで、承認は後続の実行にも引き継がれます。推奨する方法です。ユーザーが実行されるコマンドを正確に確認し、同意できます。

エージェントとして呼び出された場合は、処理を止めてユーザーに判断を委ねてください。 プロジェクトのフックを承認することは、このリポジトリがユーザーのマシン上で任意のコマンドを実行することを信頼するかどうかというセキュリティ上の判断です。この判断を下すのはエージェントではなくユーザーです。wt config approvals add を実行してコマンドを確認するようユーザーに伝えてください。ユーザーの代わりに --yes を使わないでください。ブロックされたコマンドに --yes を付けると、その実行に限って承認確認を回避し、wt config approvals add --yes を実行すると、誰も確認しないままプロジェクトが宣言するすべてのコマンドを記録します。どちらも、フックの内容をすでに管理している CI/CD パイプラインやコンテナ向けのものです。対話型エージェントが承認プロンプトを黙らせるための近道ではありません。

上級編：エージェントへの引き継ぎ

ユーザーがバックグラウンドセッションでエージェントを使ってワークツリーを作成するよう依頼した場合（「...用のワークツリーを作成して」「別のエージェントに引き継いで」など）、reference/tips-patterns.md#agent-handoffs にある tmux または Zellij のコマンドで、claude の代わりに実行中の CLI を使用し、OpenCode の run などのサブコマンドをどこに置くかについては、そのセクションの注記に従ってください。

要件（すべて満たす必要があります）：

• ユーザーが明示的に作成または引き継ぎを依頼している
• ユーザーがサポート対象のマルチプレクサーを使用している（$TMUX / $ZELLIJ を確認してください）
• ユーザーのプロジェクト指示（CLAUDE.md または AGENTS.md）または明示的なプロンプトで、このパターンが許可されている

通常のワークツリー操作にはこのパターンを使用しないでください。

並列サブエージェント（単一の Claude Code セッション）

1 つの Claude Code セッションから、それぞれ独自のワークツリーで作業する複数のサブエージェントを起動するには（ターミナルマルチプレクサーを使わず、別のペインに人間もいない場合）、親プロセスから各ワークツリーを事前に作成し、そのパスをサブエージェントのプロンプトに渡します：

wt switch --create <branch> --no-cd

次に、isolation: "worktree" を指定せずに Agent ツールを呼び出し、プロンプト内でパスを指定します：

You are working in `/abs/path/to/myproject.<branch>` on branch `<branch>`.
All edits must stay in that worktree.

--no-cd は、親プロセスが利用できないシェル統合の cd スクリプトをスキップします。ユーザーフックまたはプロジェクトフックがワークツリーを準備せず、各サブエージェントが独自にビルド／テストの手順（例：cargo run -- hook pre-merge --yes）を実行する場合に限り、--no-hooks を追加してください。依存関係をインストールしたり、gitignore 対象のビルド環境をリンクしたりする pre-start フックをスキップすると、サブエージェントはビルドできないワークツリーを渡されることになります。フックを有効にしたままにするには、プロジェクトのフックコマンドがすでに承認されている必要があります。親セッションは確認を求められないため、.config/wt.toml 内の未承認コマンドによって作成が中止されます。上の非対話型セッションでのフック承認を参照してください。

この方法で Agent { isolation: "worktree" } を使用しないでください。Claude Code は内部エージェント ID を name として WorktreeCreate フックに渡すため、wt は使い捨てブランチ上に myproject.agent-<id> という名前でワークツリーを作成します。その後、サブエージェントがその上に機能ブランチを作成すると、正規でないパス、孤立ブランチ、誤ったブランチに対して実行される post-start フックが発生します。事前に wt switch --create で作成しておけば、パス、ブランチ、フックの対象が一致します。