Worktrunk入門 — Git WorktreeでAIコーディングエージェントを並列運用する実践ガイド

Worktrunk は、Git Worktree の作成・切り替え・削除をワンコマンドに簡素化する Rust 製 CLI ツールです。Claude Code や Codex のような AI コーディングエージェントを複数同時に走らせる際、エージェントごとに作業ディレクトリを分離する用途で注目されています。本記事ではインストール手順から基本コマンド、hooks による自動化、素の git worktree 運用や Orca との比較検証まで、実務でのAIエージェント並列開発を想定して解説します。

Worktrunk とは — なぜ Git Worktree 管理ツールが必要なのか

AI コーディングエージェントに長時間タスクを任せられるようになってから、1つのリポジトリで複数エージェントを同時に走らせる運用が増えました。ただし同じ作業ディレクトリで複数エージェントを動かすとブランチの切り替えやファイル変更が衝突するため、エージェントごとに git worktree で作業ディレクトリを分離するのが定石です。

とはいえ素の git worktree コマンドは、ブランチ作成・パス指定・ディレクトリ移動・削除時のブランチ掃除まで手順が多く、エージェントを増やすほど手間が線形に増えていきます。Worktrunk はこの手間を wt switch wt list wt merge wt remove の4コマンドに集約し、worktree をブランチと同じ感覚で扱えるようにするツールです。

主な特徴は次の通りです。

MIT OR Apache-2.0 ライセンスのオープンソース。2026年3月リリースで、スター数は8,000を超えています
hooks による worktree 作成・マージ・削除時の自動化（依存インストール、テスト実行など）
hash_port フィルタでブランチごとに一意な開発サーバーのポートを自動割り当て
コピーオンライトのビルドキャッシュ共有（APFS / btrfs / XFS）で node_modules や target の再ビルドを削減
Homebrew・Cargo・Winget・pacman・Conda など主要パッケージマネージャに対応

「調べてみた」ではなく、複数エージェントを並走させる実運用を想定して要点を整理します。

インストールと初期セットアップ

環境に応じたパッケージマネージャでインストールします。

# macOS / Linux（Homebrew）
brew install worktrunk && wt config shell install

# Rust ツールチェーンがある場合（Cargo）
cargo install worktrunk && wt config shell install

# Arch Linux
sudo pacman -S worktrunk && wt config shell install

# Conda / Pixi
conda install -c conda-forge worktrunk && wt config shell install

Windows は Winget から導入します。バイナリ名が git-wt になる点に注意してください。

winget install max-sixty.worktrunk
git-wt config shell install

wt config shell install の実行が必須です。CLI のサブプロセスは親シェルのカレントディレクトリを直接変更できないため、Worktrunk はシェル関数を仕込んでディレクトリ移動を実現しています。これを実行しないと wt switch でディレクトリが切り替わりません。

基本コマンド一覧 — switch・list・merge・remove

Worktrunk の中核は4つのサブコマンドです。素の git worktree との対応は次の通りです。

やりたいこと	Worktrunk	素の git worktree
worktree へ移動	`wt switch feat`	`cd ../repo.feat`
ブランチ作成＋worktree作成＋移動	`wt switch -c feature-name`	`git worktree add -b feature-name ../repo.feature-name && cd ../repo.feature-name`
削除	`wt remove`	`cd ../repo && git worktree remove ../repo.feat && git branch -d feat`
一覧確認	`wt list`	`git worktree list`
main へ統合	`wt merge main`	squash・rebase・fast-forward・worktree削除を手動で複数ステップ実行

wt switch — 作成・移動・エージェント起動を1コマンドで

# 既存 worktree へ移動
wt switch feat

# ブランチと worktree を新規作成して移動
wt switch -c feature-auth

# worktree 作成と同時に Claude Code を起動
wt switch -c feature-auth -x claude

# GitHub の PR #123 を worktree としてチェックアウト
wt switch pr:123

ブランチ指定には ^（デフォルトブランチ）、@（現在の worktree）、-（直前の worktree）といったショートカットも使えます。

wt list — 全 worktree の状態を俯瞰

wt list --full

各 worktree のブランチ名・ステージ済み/未ステージの変更・main からのコミット位置に加え、--full オプションで CI ステータスや PR の状態まで一覧表示できます。

wt merge — squash・rebase・削除をまとめて実行

wt merge main

wt merge は「コミット → squash → rebase → pre-merge hooks → merge → pre-remove hooks → クリーンアップ → post-merge hooks」の8ステップを自動実行し、完了後に worktree とブランチを削除します。squash 時の作業内容は refs/wt-backup/<branch> に退避されるため、誤ってマージしても復元可能です。

# fast-forward できない場合はマージコミットを作る
wt merge main --no-ff

# worktree を残したままマージだけ行う
wt merge main --no-remove

wt remove — 掃除

wt remove

worktree 内から実行すると、対応するブランチごと安全に削除します。

hooksとhash_portでAIエージェント並列運用を自動化する

複数エージェントを並列稼働させる際に効いてくるのが hooks と hash_port フィルタです。設定はプロジェクト共有用の .config/wt.toml（リポジトリにコミット）と、個人設定用の ~/.config/worktrunk/config.toml の2箇所に分けて書けます。

hooks — worktree 作成・マージ・削除のライフサイクルに処理を差し込む

hooks は pre-switch / post-switch、pre-start / post-start、pre-commit / post-commit、pre-merge / post-merge、pre-remove / post-remove の5イベント×2種類が用意されています。pre- はブロッキング、post- はバックグラウンド実行です。

# .config/wt.toml（リポジトリにコミットしてチーム共有）

# 単一コマンド
pre-start = "npm ci"

# 複数コマンドを並行実行
[post-start]
server = "npm run dev -- --port {{ branch | hash_port }}"
watch = "npm run watch"

# 依存インストール後にテストを走らせる（順序付き）
[[pre-merge]]
test = "npm test"

worktree を作るたびに依存インストールと dev サーバー起動を自動化できるので、エージェントに「まず npm ci してから作業して」と指示する手間が減ります。

hash_port — ブランチごとに開発サーバーのポートを自動割り当て

hash_port フィルタはブランチ名を 10000〜19999 の範囲の整数にハッシュ化します。エージェントを5つ並列で走らせても、dev サーバーのポートが衝突しません。

[post-start]
dev = "npm run dev -- --port {{ branch | hash_port }}"

リポジトリ名とブランチ名を連結してハッシュ化することもできます。

dev = "npm run dev -- --port {{ (repo ~ '-' ~ branch) | hash_port }}"

テンプレート内では {{ branch }} {{ worktree_path }} {{ repo }} {{ owner }} などの変数のほか、wt config state vars set key=value で設定したブランチ単位のカスタム変数を {{ vars.key }} として参照できます。

並列数を増やすほどビルド・dev サーバー・エージェント本体でメモリと CPU を食うため、実務で5〜10並列を回す場合はマシンスペックに余裕を持たせておくことをおすすめします。

素のgit worktree運用・Orcaとの比較検証と実務での注意点

素の git worktree との比較

素の git worktree はブランチ名・パス指定・削除時のブランチ掃除まで毎回手動で行う必要があり、コマンド数が多いぶんタイポやディレクトリの消し忘れが起きやすいのが実感です。Worktrunk は wt switch -c と wt merge の2コマンドに集約し、加えて hooks・ポート自動割り当て・ビルドキャッシュ共有まで面倒を見てくれる点が大きな違いです。特に wt merge が squash・rebase・worktree 削除・ブランチ削除を1コマンドでこなしてくれるのは、素の git だと5〜6手順かかる作業なので体感の差が大きいです。

Orca との違い

同じく git worktree ベースで複数 AI エージェントを並列実行するツールとして Orca がありますが、性格は異なります。Orca は GUI 付きの Agent Development Environment（ADE）で、組み込みブラウザやエディタを備えた「司令塔」として使うのに対し、Worktrunk はターミナル完結の軽量 CLI で、ヘッドレスな CI・リモートサーバー・既存のエディタ/tmux 環境にそのまま組み込みやすいのが特徴です。GUI での一元管理が欲しいなら Orca、既存のターミナルワークフローに worktree 管理だけを足したいなら Worktrunk、という住み分けになります。

実務で気をつけたいポイント

コピーオンライトのビルドキャッシュ共有は対応ファイルシステム限定です。APFS（macOS）・btrfs・XFS では node_modules や target を実体コピーなしで共有できますが、reflink 非対応の ext4 やネットワークドライブでは通常のコピーになり恩恵がありません。CI 環境のファイルシステムは事前に確認しておくと良いです
hooks はシェルコマンドをそのまま実行します。.config/wt.toml をチーム共有する場合、.envrc と同様に「リポジトリを clone しただけで任意コマンドが走る」設定ファイルとして扱い、レビュー体制を敷くことをおすすめします。自分もセキュリティは学習中の身ですが、このあたりは CI/CD のサプライチェーンリスクと同じ発想で警戒しています
Windows では実行ファイル名が git-wt になるため、チームに Windows ユーザーがいる場合は手順書にコマンド名の違いを明記しておくと混乱を防げます
2026年3月リリースの若いプロジェクトのため、破壊的変更が入る可能性があります。CI では worktrunk のバージョンをピン留めしておくと安全です

まとめ

カテゴリ	ポイント
役割	git worktree の作成・切り替え・削除を `wt switch` `wt list` `wt merge` `wt remove` の4コマンドに集約するRust製CLI
セットアップ	インストール後は必ず `wt config shell install` を実行（シェル関数によるディレクトリ移動が必要）
並列運用の自動化	hooks（`pre-start`/`post-start` など5イベント×2種）と `hash_port` フィルタでエージェントごとのセットアップ・ポート割り当てを自動化
git worktree との違い	`wt merge` がsquash・rebase・worktree削除・ブランチ削除を1コマンドで実行。手動運用よりコマンド数を大幅削減
Orca との違い	Orca はGUI付きADE、Worktrunk はターミナル完結の軽量CLI。用途に応じて使い分け可能
注意点	ビルドキャッシュ共有はAPFS/btrfs/XFS限定、hooksは任意シェル実行なので設定ファイルのレビューが必要、Windowsはバイナリ名が`git-wt`