Worktrunk

Worktrunk（git worktree を管理する CLI ツール）を使用するユーザーをサポートします。

利用可能なドキュメント

リファレンスファイルは worktrunk.dev のドキュメントから同期されます:

• reference/config.md: ユーザーおよびプロジェクト設定 (LLM、フック、コマンドデフォルト)
• reference/hook.md: フックタイプ、タイミング、実行順序
• reference/switch.md、merge.md、list.md など: コマンドドキュメント
• reference/llm-commits.md: LLM コミットメッセージ生成
• reference/tips-patterns.md: 言語別のヒントとパターン
• reference/shell-integration.md: シェル統合のデバッグ
• reference/troubleshooting.md: LLM とフック (Claude 固有) のトラブルシューティング

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

2 つのタイプの設定

Worktrunk は異なるスコープと動作を持つ 2 つの設定ファイルを使用します:

ユーザー設定 (~/.config/worktrunk/config.toml)

• スコープ: 個別開発者の個人的な環境設定
• 場所: ~/.config/worktrunk/config.toml (git リポジトリにコミットされない)
• 含まれる内容: LLM 統合、worktree パステンプレート、コマンド設定、ユーザーフック、承認済みコマンド
• パーミッションモデル: 常に変更を提案して同意を得てから编集
• 参照: 詳細なガイダンスについては reference/config.md を参照

プロジェクト設定 (.config/wt.toml)

• スコープ: すべての開発者で共有されるチーム全体の自動化
• 場所: <repo>/.config/wt.toml (git にチェックイン)
• 含まれる内容: Worktree ライフサイクルのフック (pre-start、pre-merge など)
• パーミッションモデル: プロアクティブ (直接作成、git を通じて変更は可逆)
• 参照: 詳細なガイダンスについては reference/hook.md を参照

どの設定を使用するかの判定

ユーザーが設定ヘルプをリクエストする場合、以下に基づいてタイプを判定します:

ユーザー設定の指標:

• 「LLM をセットアップしたい」または「コミット生成を設定したい」
• 「worktree を作成する場所を変えたい」
• 「コミットメッセージテンプレートをカスタマイズしたい」
• 自分の環境のみに影響

プロジェクト設定の指標:

• 「このプロジェクトのフックをセットアップしたい」
• 「npm install を自動化したい」
• 「マージ前にテストを実行したい」
• チーム全体に影響

両方の設定が必要な場合: 例えば、コミットメッセージ生成のセットアップはユーザー設定が必要ですが、品質チェックの自動化にはプロジェクト設定が必要です。

コアワークフロー

コミットメッセージ生成のセットアップ (ユーザー設定)

最も一般的なリクエスト。サポートされているツールと正確なコマンド構文については reference/llm-commits.md を参照してください。

1. 利用可能なツールを検出

   which claude codex llm aichat 2>/dev/null
   

2. 何もインストールされていない場合、Claude Code を推奨 (Claude Code セッションで既に利用可能)

3. 設定変更を提案 — reference/llm-commits.md から正確なコマンドを取得

   [commit.generation]
   command = "..."  # ツール固有のコマンドについては reference/llm-commits.md を参照
   

   「この設定をあなたの設定に追加してもいいですか?」と質問してください。

4. 承認後、適用

   • 設定が存在するか確認: wt config show
   • ない場合、wt config create をガイド
   • 構造を保持しながら読み取り、変更、書き込み

5. テストを提案

   wt step commit --show-prompt | head  # プロンプトが構築されることを確認
   wt merge  # コミットされていない変更があるリポジトリで
   

プロジェクトフックのセットアップ (プロジェクト設定)

ワークフロー自動化のための一般的なリクエスト。ディスカバリープロセスに従います:

1. プロジェクトタイプを検出

   ls package.json Cargo.toml pyproject.toml
   

2. 利用可能なコマンドを特定

   • npm の場合: package.json スクリプトを読む
   • Rust の場合: 一般的な cargo コマンド
   • Python の場合: pyproject.toml を確認

3. 適切なフックを設計 (7 つのフックタイプが利用可能)

   • 依存関係 (高速、完了が必須) → pre-start
   • テスト/リント (合格が必須) → pre-commit または pre-merge
   • 長いビルド、開発サーバー → post-start
   • ターミナル/IDE 更新 → post-switch
   • デプロイ → post-merge
   • クリーンアップタスク → pre-remove

4. コマンドが機能することを検証

   npm run lint  # 存在することを確認
   which cargo   # ツールが存在することを確認
   

5. .config/wt.toml を作成

   # Worktree 作成時に依存関係をインストール
   pre-start = "npm install"
   
   # コミット前にコード品質を検証
   [pre-commit]
   lint = "npm run lint"
   typecheck = "npm run typecheck"
   
   # マージ前にテストを実行
   pre-merge = "npm test"
   

6. 選択肢を説明するコメントを追加

7. テストを提案

   wt switch --create test-hooks
   

詳細については reference/hook.md を参照してください。

既存設定へのフック追加

ユーザーが既存プロジェクトに自動化を追加したい場合:

1. 既存の設定を読む: cat .config/wt.toml

2. フックタイプを決定 - これはいつ実行されるべきか?

   • Worktree 作成 (ブロッキング) → pre-start
   • Worktree 作成 (バックグラウンド) → post-start
   • 毎回スイッチ → post-switch
   • コミット前 → pre-commit
   • マージ前 → pre-merge
   • マージ後 → post-merge
   • 削除前 → pre-remove

3. 必要に応じてフォーマット変換を処理

   単一コマンドを名前付きテーブルに:

   # 前
   pre-start = "npm install"
   
   # 後 (db:migrate を追加)
   [pre-start]
   install = "npm install"
   migrate = "npm run db:migrate"
   

4. 既存の構造とコメントを保持

コマンド追加前の検証

フックを追加する前に検証します:

# コマンドが存在することを確認
which npm
which cargo

# npm の場合、スクリプトが存在することを確認
npm run lint --dry-run

# シェルコマンドの場合、構文をチェック
bash -n -c "if [ true ]; then echo ok; fi"

危険なパターン — 以下を含むフック作成前にユーザーに警告してください:

• 破壊的なコマンド: rm -rf、DROP TABLE
• 外部依存: curl http://...
• 権限昇格: sudo

パーミッションモデル

ユーザー設定: 保守的

• 同意なしに編集しない - 常に提案された変更を表示して承認を待つ
• ツールをインストールしない - ユーザーが自分で実行するコマンドを提供
• 構造を保持 - 既存のコメントと組織を維持
• 事前に検証 - 書き込み前に TOML が有効であることを確認

プロジェクト設定: プロアクティブ

• 直接作成 - 変更はバージョン管理され、容易に可逆
• コマンドを検証 - 追加前にコマンドが存在することを確認
• 選択肢を説明 - フックが存在する理由を文書化するコメントを追加
• 危険を警告 - 追加前に破壊的な操作にフラグを立てる

一般的なタスク参照

ユーザー設定タスク

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

プロジェクト設定タスク

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

キーコマンド

# すべての設定を表示
wt config show

# 初期ユーザー設定を作成
wt config create

# LLM セットアップガイド
wt config --help

追加ドキュメントの読み込み

詳細な設定、フック仕様、トラブルシューティングについて、リファレンスファイルを読み込みます。

grep で特定のセクションを検索:

grep -A 20 "## Setup" reference/llm-commits.md
grep -A 30 "### pre-start" reference/hook.md
grep -A 20 "## Warning Messages" reference/shell-integration.md

非インタラクティブセッションでのフック承認

プロジェクトフックとプロジェクトエイリアスは初回実行時に承認を求めるため、信頼できない .config/wt.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

2 つの解決策が存在します — 誰のためにエージェントが実行されているかに基づいて選択:

• wt config approvals add — ~/.config/worktrunk/approvals.toml に承認を保存する対話的プロンプト。プロジェクトごとに 1 回実行; コマンドテンプレートが変更されるか、プロジェクトが移動されるまで呼び出し全体で永続化されます。ユーザーが信頼の決定を所有している場合は、この選択肢が正しいです。
• --yes / -y — 単一の呼び出しの承認をバイパスします。フックの内容がパイプライン自体によって制御される CI/CD に適切です。

エージェントとして呼び出される場合、停止してユーザーにエスカレーション — 事前承認はこのプロジェクトのフックをマシン上で任意のコマンドを実行することを信頼すべきかどうかについてのセキュリティ決定です。ユーザーに wt config approvals add を実行するよう指示するか、CI スタイルのワンショットバイパスを受け入れる場合は --yes を使用して再実行するよう指示してください。コマンドをブロック解除するだけの目的でユーザーの代わりに --yes を使用しないでください。

高度なトピック: エージェントハンドオフ

ユーザーがバックグラウンドセッション (「worktree をスポーン...」、「別のエージェントにハンドオフ」) でエージェント付きの worktree をスポーンするようリクエストする場合、ターミナルマルチプレクサーに適切なパターンを使用します。<agent-cli> を実行している CLI に置き換えます: Claude Code の場合は claude、OpenCode の場合は 'opencode run'。

tmux ($TMUX 環境変数を確認):

tmux new-session -d -s <branch-name> "wt switch --create <branch-name> -x <agent-cli> -- '<task description>'"

Zellij ($ZELLIJ 環境変数を確認):

zellij run -- wt switch --create <branch-name> -x <agent-cli> -- '<task description>'

要件 (すべてが真である必要があります):

• ユーザーが明示的にスポーン/ハンドオフをリクエスト
• ユーザーがサポートされているマルチプレクサー (tmux または Zellij) にいる
• ユーザーのプロジェクト命令 (CLAUDE.md または AGENTS.md) または明示的なプロンプトがこのパターンを認可

このパターンを使用しない 通常の worktree 操作の場合。

例 (tmux、Claude Code):

tmux new-session -d -s fix-auth-bug "wt switch --create fix-auth-bug -x claude -- \
  'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'"

例 (Zellij、OpenCode):

zellij run -- wt switch --create fix-auth-bug -x 'opencode run' -- \
  'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'

並列サブエージェント (単一 Claude Code セッション)

1 つの Claude Code セッションから、それぞれが独自の worktree で機能する複数のサブエージェントをスポーン — ターミナルマルチプレクサーなし、別のペインにいるユーザーなし — 各 worktree を事前作成して、パスをサブエージェントプロンプトに渡します:

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

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

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

--no-cd は親が消費できないシェル統合 cd スクリプトをスキップします; --no-hooks は各サブエージェントが独自のビルド/テストステップを実行し (例: cargo run -- hook pre-merge --yes)、worktree ごとに post-start セットアップを繰り返す必要がない場合に適切です。

Agent { isolation: "worktree" } を使用しない これのために。Claude Code は内部エージェント ID を name として WorktreeCreate フックに渡すため、wt は worktree を throwaway ブランチ上で worktrunk.agent-<id> として作成します。その後、サブエージェントが上にフィーチャーブランチを作成する場合、非正規パス、孤立ブランチ、間違ったブランチに対して発火した post-start フックで終了します。wt switch --create で事前作成するとパス、ブランチ、フックターゲットが整列します。