VibeChard

English · 简体中文 · 繁體中文 · 日本語 · 한국어

AI コーディングエージェント向け、Apple 開発のためのタスク単位で隔離された worktree。 同じ Xcode プロジェクトに対して Claude / Codex / Copilot / Cursor を複数同時に走らせても、 build.db のロック、DerivedData の取り合い、シミュレーターの衝突が起きません。

brew install maples7/tap/vch

あとはどの Apple プロジェクトでも：

vch new add-paywall          # 隔離された worktree + agent ブランチを作成
vch add-paywall              # その worktree のシェルに入る（隔離が有効な状態）
                             # → いつもどおり xcodebuild / swift test を実行
vch test add-paywall --device "iPhone 16"
vch remove add-paywall

それだけです。各エージェントは専用の worktree、専用の DerivedData、専用のシミュレータークローンを持ちます——あなたの ~/Library/Developer/ は 1 バイトも変更されません。

ステータス: 安定版（1.0）。 CLI のインターフェースとディスク上の .vch/state.json スキーマ（v1）は凍結されています。変更はセマンティック バージョニングに従い、破壊的変更は 2.0 まで行いません。

なぜ専用の CLI が必要なのか

汎用の git-worktree マネージャ（Rift、Emdash、Taskpods、Workie など）が解決するのは「ソースツリーの隔離」だけです。しかし Apple のツールチェインには 他にも少なくとも 7 つの共有リソースがあり、xcodebuild を並列に走らせると互いに衝突して非決定的な失敗を引き起こします：

リソース	隔離しないとどうなるか	VibeChard の対応
DerivedData	モジュール再ビルドの繰り返し、キャッシュ汚染	-derivedDataPath <wt>/.agent-build/DerivedData
ModuleCache.noindex	並行下で Clang モジュールキャッシュが破損	worktree ごとに CLANG_MODULE_CACHE_PATH
SwiftPM グローバルキャッシュ	Package.resolved の書き込み競合	worktree ごとに -clonedSourcePackagesDirPath
xcresult バンドル	後勝ちで上書き	worktree ごとに -resultBundlePath
シミュレーターデバイス	同じ iPhone 16 に 2 タスクが同時インストール	タスクごとに xcrun simctl clone
エージェントが PATH から xcodebuild を引く	注入したフラグを素通り	PATH シムで自動的にフラグを注入
ソースツリー	標準的な対処	git worktree + agent/<name> ブランチ

BYO Agent (Bring Your Own Agent) です——Claude、Codex、Copilot、Cursor、シェルが叩けるものなら何でも。VibeChard は AI ベンダーのラッパーではありません。テレメトリなし、ネットワーク通信なし、SDK 依存なし。

「git worktree と 5 行のシェル関数で十分じゃない？」

もっともな疑問です——最初は私もそうしました。ソースツリーは隠離できますが、エージェントが worktree 内で叩く xcodebuild は依然として以下のグローバルな場所を参照します：

• ~/Library/Developer/Xcode/DerivedData/MyApp-<hash>/（グローバル既定値）
• ~/Library/Developer/Xcode/DerivedData/ModuleCache.noindex/（グローバル）
• ~/Library/Caches/org.swift.swiftpm/（グローバル）
• ~/Library/Developer/CoreSimulator/Devices/<UDID>/（グローバル）

これらのいずれかが共有されている限り、並列の xcodebuild は競合します。解決策は二つ：

1. 毎回正しいフラグを渡す。 すべての xcodebuild と swift test で -derivedDataPath / -clonedSourcePackagesDirPath / -resultBundlePath を忘れずに。Tuist、Fastlane、各カスタムテストスクリプト、シェルアウトする Package.swift プラグインにも教え込む。そして AI エージェントにも忘れないよう念を押す——絶対に忘れます。
2. xcodebuild の前に PATH シムを置く。 誰がどんな方法で呼んでも、フラグが必ず効く状態にする。

VibeChard は (2) を採っています。これが「.zshrc のスニペット」ではなく CLI である唯一の理由です。

インストール

Homebrew（推奨）

brew install maples7/tap/vch

安定版では、Apple Silicon の macOS 14+ と Intel の macOS 15+ 向けに ビルド済みの Homebrew bottle を提供します。互換性のある bottle があれば、 vch のコンパイルやソースビルド時の Xcode バージョンチェックは不要です。 その他の構成と --HEAD はソースからビルドします。macOS 更新後に古い Xcode を理由に Homebrew が拒否する場合は、下記の手順で手動ビルドして ください。Apple プロジェクトのビルドには引き続き Xcode が必要です。

formula は以下をインストールします：

• vch を Homebrew の bin/ に（PATH に載る）
• vch-xcodebuild-shim を libexec/ に（意図的に PATH には載せない——タスクごとの .vch/bin/ に vch exec が張るシンボリックリンク経由でのみ到達されるべきものです）
• Bash、Zsh、Fish の補完スクリプト

ソースからビルド

ビルドホスト: macOS 13+ と Xcode 15.3+（Swift 5.10+）。生成される vch バイナリは macOS 13+ を対象とします。

git clone https://github.com/maples7/VibeChard.git
cd VibeChard
swift build -c release
ln -s "$PWD/.build/release/vch" /usr/local/bin/vch    # CLI を置いている場所に合わせて

Apple プラットフォームのサポート

隔離の仕組み——worktree、PATH shim、DerivedData / ModuleCache / SwiftPM / xcresult のリダイレクト——はプラットフォーム非依存で、あらゆる xcodebuild 呼び出しに適用されます。シミュレータのクローンとウォームテンプレートは iOS・watchOS・tvOS・visionOS 向けにパラメータ化されています。日々の検証は iOS に集中しており、vch run（インストール + 起動）で最もよく通るパス です。他の 3 つは同じコードパスでサポートされますが、実機での dogfooding は 少なめです。macOS（実機ターゲット）プロジェクトのビルドとテストも問題なく 動作します——シミュレータのクローンを使わないだけです。

クイックスタート

git 管理下の任意の Apple プロジェクト内で：

# 1. agent/add-paywall 上に隔離された worktree を起こす
vch new add-paywall

# 2. その中のシェルに入る（PATH シムが有効）
vch add-paywall
# このシェル内で：
#   xcodebuild build              ← -derivedDataPath が自動注入される
#   swift test                    ← モジュールキャッシュと SwiftPM の clone 先が隔離済み
#   exit                          ← 元のシェルに戻る

# 3. シェルに入らず直接 xcodebuild を呼ぶことも可能：
vch build add-paywall --scheme MyApp
vch test  add-paywall --scheme MyApp --device "iPhone 16"

# 4. worktree 内で直接エージェントを走らせる：
vch new fix-toast --exec "claude"     # 隔離された worktree 内で claude を起動
vch new triage --copy-untracked       # .env / .vscode など未追跡ファイルも一緒にコピー
vch new --adopt-current               # 現在の linked worktree を採用し、そのディレクトリ名を使う
vch exec fix-toast -- npm run lint    # worktree 内でワンショット実行

# 5. 確認とクリーンアップ
vch list
vch path add-paywall                  # worktree の絶対パス
vch remove add-paywall                # worktree + ブランチ + シミュレータークローンを削除

Agent runbook

AI エージェントがタスクを進める場合は、現在のバージョンに対応する runbook を渡してください：

vch runbook

vch <name> / vch exec の中では、子プロセスにも同じ tag 固定リンクを 指す VCH_AGENT_RUNBOOK_URL が渡されます。ソース上のコピーは docs/agent-runbook.md です。

ワークフロー：連続したタスク群

vch が本当に振るうのは、単発タスクではなく互いに独立した短いタスクを連続 （または並行）で回すケースです。各タスクはそれぞれの worktree で進め、取り込んで から次に進みます。代表的なループ：

# 計画：A → B → C、それぞれをマージしてから次に進む。

# タスク A — 実装、テスト、レビュー。
vch new task-a
cd "$(vch path task-a)"
# ...編集...
vch build task-a --scheme MyApp
vch test  task-a --scheme MyApp --device "iPhone 16"
git commit -am "perf: task A"
vch open task-a                       # IDE でレビュー

# 承認されたらメイン worktree からマージ：
cd /path/to/main-worktree
git merge --no-ff agent/task-a -m "Merge agent/task-a: <subject>"
vch remove task-a                     # worktree + ブランチ + シミクローンをまとめて削除

# タスク B はクリーンな develop から同じサイクルを繰り返す。
vch new task-b
# ...

vch new のたびに SwiftPM 解決キャッシュ、DerivedData、モジュールキャッシュ （いずれも .vch/ 下）が独立で作られるため、並行中の 2 タスクが SPM ロック争いや Xcode ビルドキャッシュの無効化で互いをブロックすることはありません。別のシェルで 複数の vch test を同時に走らせても Core Data ストアの衝突やシミュレーターの 上書きは起きません。

build/test ループをスクリプト化する場合は、生の vch exec ... xcodebuild ... より vch build / vch test を優先して ください。高レベルコマンドは簡潔なサマリー、ログ、result bundle のパスを そのまま扱えます：

vch test task-a --scheme MyApp --device 'iPhone 16' \
  --only-testing MyAppTests/Foo

低レベルのツールを直接呼ぶ必要がある場合も、.vch/state.json を 手読みするより安定した vch state <name> --field <dotted> を使ってください。

Cookbook

組み込みコマンドではないが、よく聞かれる使い方 —— WIP 中のタスクから 分岐する、テストの一部だけを実行する、長期タスクを最新に保つ、 vch land で生成物を残す、warm シミュレーターテンプレートで初回起動を スキップする、タスクごとのシミュレーター状態をリセットする、テンプレート が Booted で詰まったときの対処、マージ済みタスクの一括削除など。

→ 詳細は docs/cookbook.md を参照（英語単一ソース、 AGENTS.md ルール #10 を参照）。

コマンド一覧

コマンド	何をするか
vch new [<name>]	worktree と agent/<name> ブランチを作成、または現在の linked worktree を採用（--adopt-current では <name> を省略可；--exec "<cmd>"、--copy-untracked、--seed-spm-from <task>、--cd）。
vch list	ワークスペース内の全タスクを一覧表示（--json、-v、--git-status）。
vch state <name>	タスクの .vch/state.json を表示（--json、--field <dotted>）。
vch path <name>	タスクの worktree の絶対パスを表示。
vch open [<name>]	worktree を IDE で開く（--with xcode/code/cursor/…）。
vch <name>	worktree のシェルに入る。分離環境と PATH shim が有効。
vch exec <name> -- <cmd...>	タスクの worktree 内で任意コマンドを実行（分離有効）。
vch build [<name>]	xcodebuild build を実行し -derivedDataPath / -clonedSourcePackagesDirPath を自動注入。タスク worktree 内では <name> を省略可（--scheme、--project、--workspace、--runtime、--erase-clone、--shutdown-template、--existing-sim、--verbose）。
vch test [<name>]	xcodebuild test を実行し -resultBundlePath を注入。タスク worktree 内では <name> を省略可。シミュレーターは遅延クローン（--device、--project、--workspace、--runtime、--only-testing、--skip-testing、--rerun、--rerun-failed、--erase-clone、--shutdown-template、--test-execution-idle-timeout、--progress-interval）。
vch run [<name>]	タスクのシミュレータークローン上でビルド・インストール・起動。タスク worktree 内では <name> を省略可（--project、--workspace、--erase-clone、--shutdown-template、--existing-sim、-- launch-args）。
vch logs <name>	タスク直近のビルド/テストの完全な xcodebuild ログを表示（--test/--build）。
vch sim {clone,erase,shutdown,info} <name>	タスク用シミュレータークローンを明示的に管理。vch sim clone --device <name> を繰り返すことで 1 タスクが複数（iOS + watchOS など、プラットフォームごとに 1 つ）の クローンを持てる (#99)。
vch sim warm-template {create,list,remove}	共有の warm シミュレーターテンプレートを管理（iOS / watchOS / tvOS / visionOS、#47 / #58）。
vch land <name>	agent/<name> を base にマージして後始末（--into、--no-ff/--ff-only/--squash、--keep、--push/--push-to、--dry-run）。
vch sync <name>	base の upstream を fetch してタスクブランチを rebase（--onto、--merge、--no-fetch、--dry-run）。
vch remove <name>	vch が作成した worktree、ブランチ、シミュレータークローンを削除。採用したタスクは vch 状態のみ解除（--allow-dirty、--force、--allow-unmerged、--keep-sim）。
vch prune	base に完全マージ済みのタスクを一覧／削除（--rm、--allow-dirty、--force、--keep-sim、--json）。
vch repair	git worktree list の実状に合わせて .vch/state.json を再同期。
vch clean <name>	タスクの DerivedData / ModuleCache を削除（--swiftpm、--logs、--all、--dry-run、--kill-stuck-tests）。
vch doctor	孤児シミュレータークローン、不正バインディング、壊れた state.json を検出（--clean、--bug-report、--json）。
vch shellenv	vch_cd / vch_new / vch_clean の shell 補助関数を出力（bash/zsh）。
vch completions install	zsh / bash / fish の補完スクリプトをインストール（--shell、--print、--force）。
vch runbook	バージョン固定の Agent runbook URL と Homebrew インストール済みドキュメントパスのヒントを表示（--json）。
vch version	バージョンとツールチェーン情報を表示（--json で機械可読）。

<name> を受け取るコマンドは現在のワークスペースから補完されます —— 補完スクリプトをインストールして <TAB> を押すだけ。完全な flag リファレ ンスは docs/commands.md を参照。

隔離の仕組み

タスクの worktree 内では `/.vch/bin/` が `PATH` の先頭に挿入され、そこに `xcodebuild`、`xcrun`、`swift` のシンボリックリンクがあり、すべて `vch-xcodebuild-shim` を指しています。

シムは 3 つの環境変数（VCH_DERIVED_DATA_PATH、VCH_SPM_CLONE_DIR、 VCH_RESULT_BUNDLE_PATH）を読み、ユーザーが明示的に渡していない場合は対応するフラグを xcodebuild の argv に注入し、ターゲットディレクトリを mkdir -p で作成、その後 /usr/bin/xcrun -f xcodebuild で本物の xcodebuild のパスを解決して execv（PATH を経由しないので自分自身を再帰呼び出しすることはありません）。xcrun と swift に対しては透過的にパススルーします。

結果：エージェントが起動しうるあらゆるツール——xcodebuild、swift test、 Tuist、内部で xcodebuild を呼び出すスクリプト——が自動的に隔離されます。フラグを手で渡す必要はありません。

vch build、vch test、vch run は PATH シムをスキップして直接 xcodebuild を同じフラグで呼び出します。呼び出し地点で引数がすべて分かっているためです。

vch exec / vch <name> が子プロセスに注入するもの

vch <name>（= vch exec <name> -- $SHELL）と vch exec <name> -- <cmd> は、あなたの環境の上に決定的な env を一段重ねます。これは vch build / vch test / vch run が使うものとまったく同じ集合 なので、vch <name> の中で手で xcodebuild を叩いても挙動は vch build と一致します。「タスクの環境に入りたい」専用の別コマンドは 基本必要ありません — vch <name> がすでにそれです：

変数	設定値
VCH_TASK_NAME	タスク名（例 add-paywall）。PS1 や端末タイトルに便利。
VCH_TASK_ROOT	worktree の絶対パス。
VCH_AGENT_RUNBOOK_URL	この vch バイナリに対応するバージョン固定の Agent runbook URL。
VCH_DERIVED_DATA_PATH	<wt>/.agent-build/DerivedData（シムが読む）。
VCH_SPM_CLONE_DIR	<wt>/.agent-build/SourcePackages（シムが読む）。
VCH_RESULT_BUNDLE_PATH	<wt>/.agent-build/Result.xcresult（シムが読む）。
VCH_RESULT_BUNDLE_DIR	result bundle の親ディレクトリ。
CLANG_MODULE_CACHE_PATH	<wt>/.agent-build/ModuleCache（clang が読む）。
SWIFTPM_CACHE_DIR	<wt>/.agent-build/SourcePackages（SwiftPM が読む）。
DEVELOPER_DIR	xcode-select -p で解決したホストの選択 Xcode — ユーザーが既に export していない場合のみ注入。
SIMCTL_CHILD_SIMULATOR_UDID	タスクに紐づくシミュレータークローン — クローンが紐付いているときだけ設定。
PATH	先頭に <wt>/.vch/bin を付加して xcodebuild / xcrun / swift をシム経由に。

vch がユーザーの export 済みの値を上書きすることはありません — vch exec の前に手動で export した値が常に優先されます。

設定

ありません。タスクごとの状態はすべて <worktree>/.vch/state.json に収まります。~/.vchrc も .vch.toml もグローバル設定ファイルもありません。唯一の実行時ノブは上記の VCH_* 環境変数です（通常は vch exec が自分でセットするので、手動で触る必要はほとんどありません）。vch build/vch test/vch run はホストで選ばれている DEVELOPER_DIR（xcode-select -p で解決）を子プロセスに伝播します。手動で環境変数を設定すれば上書きできます。

vch new が eval "$(vch shellenv)" のヒントを表示した場合、VCH_NEW_HINT=0 で抑制できます（あるいはシェル helper をインストールすれば自動的に消えます）。

warm template を手動で起動して（例: 手動 UI チェック）から vch build / vch test / vch run がクローンを拒否する状況によく遭遇するなら、VCH_SHUTDOWN_TEMPLATE_ON_CLONE=1 を設定すると、このシェルやリポジトリで --shutdown-template がデフォルトになります。グローバルのデフォルトは保守的なまま（vch は共有テンプレートを自動で触りません — hard rule #9）なので、これはユーザー単位・リポジトリ単位のオプトインです。明示的な --shutdown-template は常に優先されます。

VibeChard ではないもの

• AI ベンダーのラッパーではありません。 SDK も API キーもモデル抽象もありません。好きなエージェントを使ってください——VibeChard は並列セッションを安全にすることだけを担当します。
• クロスプラットフォームではありません。 設計上 Apple 専用です。プロジェクトの価値は Xcode ツールチェインへの深さにあり、広さにはありません。
• CI オーケストレータではありません。 ローカルのターミナルで、ディスク上の worktree に対して動作します。CI マトリクスは別の問題です。

よくある質問

Tuist / Fastlane / xcbeautify と組み合わせて使えますか？

使えます。PATH シムは誰が起動しても xcodebuild の呼び出しをすべてキャッチします。Tuist が生成する実行、Fastlane の gym / scan、 xcbeautify の上流パイプ、最終的に xcodebuild を叩くカスタムテストスクリプト — どれもタスクごとの -derivedDataPath / -clonedSourcePackagesDirPath / -resultBundlePath が自動で注入されます。フラグの取り回しは不要です。

CocoaPods / Carthage は？

問題ありません。依存解決のステップは xcodebuild を経由しないので隔離不要。ビルドステップは結局 xcodebuild を呼ぶのでシムがキャッチします。 Pods/ と Carthage/ ディレクトリはソースと同じ worktree 内にあるので、 git worktree 自体で隔離されます。

SwiftPM のみのプロジェクト（.xcodeproj なし）？

動きます。swift build / swift test は既定で worktree ごとの .build/ ディレクトリに書き込むため、シムによるフラグ注入なしで初めから隔離されています。シムは透明な passthrough として swift をラップしますが argv は変更しません。

vch remove 時に未コミットの変更はどうなる？

失われません — vch remove は dirty な worktree では明確なメッセージとともに中断します。--allow-dirty を付けると上書きで削除（未コミット変更を失います）、--allow-unmerged を付ける（または両方併用）と未マージのコミットを持つブランチも削除できます。無言で破壊的に動くパスはありません。

AI エージェントなしでも使えますか？

はい。「並列のサンドボックスが欲しい」シナリオすべてに使えます：同じ機能の別実装を 2 つ並走させる、長い test suite を走らせている裏でメイン worktree でコーディングを続ける、など。CLI はエージェントに依存しません —いわゆる「エージェント連携」は --exec "<your command>" だけです。

ソースからビルド・テスト

swift build -c release
./.build/release/vch version
swift test --parallel

CI は push のたびに同じコマンド + シムのスモークテストを実行します： .github/workflows/ci.yml。

ライセンス

Apache-2.0。CLA なし、テレメトリなし、ネットワーク通信なし。