CoW でつくる worktree で分離された並列環境
Claude Code などのエージェントを何本も並行で走らせるには、1 本ごとに依存・URL・Cookie・DB まで分かれた作業場所を、待たずに用意できる必要がある。git worktree に APFS の clonefile(CoW)・portless・sashiki を組み合わせて 1 コマンド数秒で作り、単一アプリと pnpm モノレポで実測した。git worktree・CoW・Cookie・リバースプロキシの仕組みを図で解説し、何本まで増やせるかの上限と、ポートの衝突でエラーにならずに別のエージェントの API と DB に接続してしまう問題と対策もまとめる。
TL;DR
- エージェントを並行で走らせる単位は git worktree。 ただし worktree はソースコードしか分けないので、node_modules・
.env・port・Cookie・DB は自分で分ける必要がある - node_modules は APFS の clonefile(CoW)で複製する。 125MB の node_modules が 1.2 秒で複製でき、空き容量はほぼ減らない。pnpm のモノレポでも、シンボリックリンクが相対パスなのでそのまま動く
- URL と Cookie は portless で分ける。 dev サーバーを
portless run経由で起動すると、worktree ごとにhttps://<ブランチ名>.<アプリ名>.localhostが割り当てられる。エージェントは自分の URL で動作を確かめられ、Cookie も混ざらない - モノレポでは、web から同じ worktree の API を
portless getで見つける。 アプリ名はwebではなくweb.<project>のように明示する - DB は sashiki でブランチごとに分ける。 worktree 1 つあたりの作成は約 3 秒
- 「無限」の上限はメモリで決まる。 web と API を動かす worktree 1 つで約 0.9GB 使った。64GB の Mac なら、ほかの用途を差し引いて数十本が目安
- portless のポート割り当てには TOCTOU の競合状態がある。 同時に起動した dev サーバーに同じポートが渡ることがあり(起動に時間がかかるアプリほど起きやすい)、
tsx watchのように bind 失敗後も動き続けるものでは、片方の web がエラーにならずに別の worktree の API と DB に接続する。bind に失敗したら dev ごと止めるようにした
全体像
最初に、できあがる環境の全体を示します。エージェント 1 本につき worktree を 1 つ割り当て、依存・設定・URL・DB も worktree ごとに分けます。
実線が「worktree ごとに分かれているもの」、点線が「共有しているもの」です。共有しているものは、どれも書き込むと分かれるか、読むだけのものです。そのため、エージェント同士が互いの作業に影響しません。
なぜ作業場所を分けるのか
Claude Code などのコーディングエージェントは、1 つ指示すると数分から数十分ひとりで作業します。その間に別の作業を別のエージェントに任せられれば、人間は指示とレビューに専念できます。
エージェントを並行で走らせるには、1 本ごとに独立した作業場所が要ります。同じディレクトリで 2 本が動くと、片方の変更がもう片方のテストを壊します。
そこで使うのが git worktree です。ただし、worktree が分けるのは git が管理しているファイルだけです。新しい worktree を作った直後は次の状態になっています。
| 状態 | 並行で動くエージェントにとって困ること | |
|---|---|---|
| node_modules | 無い | 作業を始める前に毎回 install を待つ。ディスクも worktree の数だけ消費する |
.env | 無い | 起動できない。手でコピーする必要がある |
| dev サーバーのポート | 全部 5173 | 2 本目以降が別のポートにずれ、エージェントがどの URL で確かめればよいか分からない |
| Cookie | localhost で共有 | Cookie はポートを区別しないので、片方のログイン状態がもう片方に混ざる |
| DB | 共有 | 片方のマイグレーションやテストデータが、もう片方のエージェントの結果を変える |
エージェントを好きなだけ増やすには、これらがすべて分かれた作業場所を、待たずに用意できる必要があります。ここでは 1 コマンド数秒で作れるようにします。
./scripts/wt-new.sh feat-a
# → ../<repo>.feat-a が数秒でできて、node_modules と .env が揃っている
cd ../<repo>.feat-a && npm run dev
# → https://feat-a.<app>.localhost で起動。ポートも Cookie も DB も他の worktree と独立
エージェントには、この worktree のディレクトリと URL を渡して作業させます。
以降、使う技術ごとに仕組みを説明してから、実際の作り方に入ります。
仕組み 1: git worktree
git の中身は 2 つに分かれている
git のリポジトリは、大きく 2 つに分かれています。
.gitディレクトリ: すべてのコミット(ファイルの中身の履歴)と、ブランチがどのコミットを指しているかの情報- 作業ディレクトリ: いま編集しているファイル。あるブランチの状態を
.gitから取り出したもの
普通のリポジトリでは、作業ディレクトリは 1 つだけです。別のブランチで作業するには git switch で切り替える必要があり、同時に 2 つのブランチを開けません。
clone と worktree の違い
同時に 2 つのブランチを開く方法は 2 つあります。
- clone を 2 回すると、
.gitも 2 つできます。履歴を二重に持つのでディスクを使い、片方で作ったブランチやコミットはもう片方から参照できません(push と fetch が要ります) - worktree は、
.gitを 1 つのまま、作業ディレクトリだけを増やします。どの worktree で作ったコミットも、すぐに他の worktree から参照できます
worktree の実体
worktree のディレクトリにある .git は、ディレクトリではなく 1 行のファイルです。
$ cat ../worktree-lab.diagram/.git
gitdir: /Users/inouetaishi/gh/worktree-lab/.git/worktrees/worktree-lab.diagram
指している先には、その worktree 専用の情報が入っています。
- コミットとブランチ(
objects/・refs/)は全 worktree で共有します - 「いまどのブランチか」(
HEAD)と「ステージした内容」(index)は worktree ごとに分かれます
1 つのブランチは、同時に 1 つの worktree でしか開けません。2 つ目で開こうとするとエラーになります。
$ git worktree add ../worktree-lab.d2 diagram-probe
fatal: 'diagram-probe' is already checked out at '/Users/inouetaishi/gh/worktree-lab.d1'
同じブランチを 2 か所で編集すると、どちらの変更が正しいか分からなくなるため、git がこの操作を拒否します。
worktree が分けないもの
git worktree add が作業ディレクトリに取り出すのは、git が管理しているファイルだけです。.gitignore に入っているものは取り出されません。
node_modules と .env は、自分で用意する必要があります。node_modules は install すれば作れますが、数十秒から数分かかり、ディスクも worktree の数だけ使います。これを一瞬で、ほぼディスクを使わずに用意するのが次の CoW です。
仕組み 2: CoW(copy-on-write)と clonefile
ファイルは「名前」と「中身のブロック」に分かれている
ファイルシステムの中で、1 つのファイルは次の 2 つでできています。
- inode: ファイルの管理情報。サイズや更新時刻と、「中身がディスクのどのブロックにあるか」を持つ
- データブロック: ファイルの中身そのもの。ディスク上の決まった大きさの領域
ディレクトリに並んでいるファイル名は、inode を指しています。
3 つのコピーのしかた
ファイルを「複製」する方法は 3 つあり、何を共有するかが違います。
| 時間 | ディスク | 片方を書き換えると | |
|---|---|---|---|
| 普通のコピー | 中身の量に比例 | 中身の分だけ増える | もう片方は変わらない |
| ハードリンク | 一瞬 | 増えない | もう片方も変わる(同じ inode なので) |
| clonefile | 一瞬 | 増えない | もう片方は変わらない |
ハードリンクは速くて省容量ですが、同じファイルを 2 つの名前で呼んでいるだけです。片方の worktree で依存を書き換えると、もう片方も書き換わってしまいます。
clonefile は、inode は別々に作り、データブロックだけを共有します。速さと省容量はハードリンクと同じで、分離は普通のコピーと同じです。
書き込んだときに初めて分かれる
clonefile が別々のファイルとして振る舞えるのは、書き込んだブロックだけを新しく確保するからです。これを copy-on-write(CoW)と呼びます。
- 複製した直後は、どちらのファイルも同じ 3 ブロックを指しています。ディスクの使用量は 1 ファイル分です
- b.js の 2 番目のブロックに書き込むと、新しいブロック 2’ が確保され、b.js だけがそこを指すようになります。a.js は元のまま
- 増えたディスクは、書き込んだ 1 ブロック分だけです
macOS の標準ファイルシステムである APFS は、このしくみを clonefile(2) というシステムコールで提供しています。cp に -c を付けると使えます。
cp -cR "$donor/node_modules" "$dst/node_modules"
node_modules は、作ったあとはほとんど書き換えません。そのため、何万ファイルあっても複製はほぼ一瞬で、ディスクもほぼ使いません。
ディスク使用量は du ではなく df で見る
CoW で複製したものの容量を測るときは注意が要ります。
du はファイルごとのサイズを足すので、共有しているブロックを二重に数えます。実際に何バイト使ったかは、df で空き容量の差を見る必要があります。
仕組み 3: port・Cookie・reverse proxy
Cookie はポートを区別しない
ブラウザは、Cookie をホスト名ごとに保存します。ポート番号は区別しません。
ポートで分けると、A でログインした Cookie が B にも送られます。ログイン状態やセッションが混ざり、片方のエージェントの動作確認がもう片方の状態に左右されます。ホスト名(サブドメイン)を分ければ、Cookie の保存先も分かれます。
.localhost とリバースプロキシ
feat-a.app.localhost のような名前を使えるのは、.localhost で終わる名前が自分のマシン(127.0.0.1)を指す決まりになっているからです。Chrome と Firefox は、DNS に問い合わせずにそう解決します。
ただし、名前で分けても、届く先は同じ 127.0.0.1 です。どのアプリに渡すかを決めるのが リバースプロキシです。リクエストのホスト名を見て、対応するアプリのポートに転送します。
portless は、このリバースプロキシを開発用にまとめたツールです。
- dev サーバーを
portless runで起動すると、空いているポートを選んで dev サーバーに渡し、ホスト名とポートの対応(ルート)を登録する。dev サーバーが終了すると外す - 自前のローカル CA で証明書を作り、
https://で受ける - git の linked worktree の中で起動すると、ブランチ名をホスト名の先頭に付ける
Caddy や nginx で同じことをするなら、ホスト名とポートの対応を設定ファイルに書いておく必要があります。portless は、起動したアプリが自分でルートを登録するので、worktree を増やしても設定を書き足す必要がありません。
構成
ここまでの仕組みを、次のように組み合わせます。
| 分けるもの | 方法 |
|---|---|
| node_modules | APFS の clonefile(cp -cR)で複製する。ロックファイルが元と違うときだけ install する |
.env など git 管理外の設定 | cp -c で複製する |
| URL・port・Cookie | dev サーバーを portless 経由で起動し、worktree ごとのサブドメインにする |
| DB | sashiki でブランチ用の MySQL を作り、.env.local の DATABASE_URL を差し替える |
題材は 2 つ用意しました。どちらも表示名を Cookie に保存する TODO アプリです。
- 単一アプリ: React Router(v8、Vite)+ MySQL。npm
- モノレポ: pnpm workspace で、web と API を別々の dev サーバーとして動かす
worktree-monorepo-lab/
├── apps/
│ ├── web/ # React Router v8(SSR)。loader から API を呼ぶ
│ └── api/ # Hono + mysql2
├── packages/
│ └── shared/ # web と api で共有する型
└── scripts/
├── wt-new.sh
└── wt-rm.sh
モノレポはルートの pnpm dev で web と api を並列に起動します。
{
"scripts": {
"dev": "pnpm -r --parallel --filter './apps/*' dev"
}
}
--filter './apps/*' はクォートが必要です。クォートしないとシェルが glob を展開し、None of the selected packages has a "./apps/web" script で失敗します。
wt-new.sh がやること
以下、各段階を詳しく見ていきます。
node_modules: clonefile で複製する
cp -cR "$donor/node_modules" "$dst/node_modules"
複製したファイルは別の inode なので、片方の worktree で依存を追加・更新しても、もう片方には影響しません。
pnpm のモノレポでもそのまま複製できる
pnpm の node_modules は、ルートの node_modules/.pnpm に実体があり、各パッケージの node_modules からは シンボリックリンク(symbolic link。別の場所を指す特殊なファイル)で参照されます。
シンボリックリンクはすべて相対パスです。node_modules/.modules.yaml に入っている絶対パスも、pnpm の共有ストアの場所(storeDir)だけでした。
相対パスなので、ルートと apps/*・packages/* の node_modules を同じ相対位置に複製すれば、複製先の中で正しく解決されます。
for rel in node_modules apps/*/node_modules packages/*/node_modules; do
cp -cR "$donor/$rel" "$dst/$rel"
done
.pnpm の中のファイルは pnpm のストアへのハードリンクですが、clonefile で複製すると別の inode になります。片方の worktree で pnpm --filter api add left-pad しても、メインと他の worktree には入りませんでした。
複製元を固定する
複製元(donor)はメインの checkout に固定しています。注意点は、donor で install が走っている最中に複製しないことです。書きかけの node_modules を複製すると、壊れた状態がそのままコピーされます。
スクリプトでは、install 系のコマンドを実行しているプロセスのうち、カレントディレクトリが donor のものを探して待ちます。
donor_installing() {
local pid cwd
for pid in $(pgrep -f '(npm|pnpm|yarn|bun)( [^ ]+)* (install|i|ci|add|remove|rm|update|up)( |$)' || true); do
cwd=$(lsof -a -p "$pid" -d cwd -Fn 2>/dev/null | sed -n 's/^n//p')
[[ $cwd == "$donor" || $cwd == "$donor"/* ]] && return 0
done
return 1
}
ロックファイルが違うときだけ install する
worktree のブランチがメインと違う依存を持っていることもあります。複製したあとにロックファイルを比べ、違うときだけ install して差分を埋めます。
if ! cmp -s "$donor/$lockfile" "$dst/$lockfile"; then
(cd "$dst" && "$pm" install)
fi
clonefile で複製した node_modules がすでにあるので、install はロックファイルの差分だけを入れます。1 パッケージ追加したブランチで、npm は 0.6 秒、pnpm は 0.4 秒でした。
node_modules/.vite(Vite の依存プリバンドル)も一緒に複製されるので、dev サーバーの初回起動も速くなります。逆に .react-router/(型生成の出力)は複製せず、各 worktree で生成させます。
URL と Cookie: portless でサブドメインを分ける
package.json の dev を portless run 経由にするだけです。元のコマンドは dev:plain として残します。
{
"scripts": {
"dev": "portless run react-router dev",
"dev:plain": "react-router dev"
}
}
React Router(Vite)は環境変数 PORT を見ませんが、portless が --port と --host を自動で付けて起動します。
2 つの worktree で起動した状態はこうなります。
$ portless list
https://wt-test-b.worktree-lab.localhost -> localhost:4350
https://wt-test-a.worktree-lab.localhost -> localhost:4795
ブランチ名に / があるときは、最後のセグメントが使われます(feat/slash-check → slash-check.worktree-lab.localhost)。
A の URL で表示名を保存すると、Cookie は wt-test-a.worktree-lab.localhost に限定して保存され、B へのリクエストには付きませんでした(curl とブラウザの開発者ツールで確認)。
モノレポではアプリ名を明示する
portless は、名前を指定しないとパッケージ名から付けます。apps/web のパッケージ名が web だと https://web.localhost になり、他のプロジェクトの web とぶつかります。そこで、アプリごとに名前を明示します。
// apps/api/package.json
"dev": "portless run --name api.monorepo-lab tsx watch src/index.ts"
worktree の中では、これにブランチ名が付きます。
web から同じ worktree の API を見つける
web の loader は API をサーバー側で呼びます。このとき、自分と同じ worktree の API を呼ぶ必要があります。違う worktree の API を呼ぶと、違うエージェントの DB を読み書きすることになります。
portless get <name> は、portless run と同じ規則で URL を組み立てて出力します。worktree の中で実行すると、ブランチ名の付いた URL が返ります。
$ cd ../worktree-monorepo-lab.probe/apps/api
$ portless get api.monorepo-lab
https://probe.api.monorepo-lab.localhost
web の dev スクリプトで、これを環境変数に入れます。
// apps/web/package.json
"dev": "API_URL=${API_URL:-$(portless get api.monorepo-lab)} portless run --name web.monorepo-lab react-router dev"
1 回の画面表示で、リクエストは次のように流れます。
API は HTTPS で、portless のローカル CA で署名されています。portless は子プロセスに NODE_EXTRA_CA_CERTS を渡すので、web のサーバー側の fetch からもそのまま呼べました。
フロントとバックを別ブランチで動かす
モノレポでは、フロントエンドとバックエンドを別のブランチで動かしたいこともあります。たとえば、フロントエンドを feat-ui で作りながら、バックエンドは feat-api で作業中のものを使う場合です。
上の dev スクリプトは API_URL=${API_URL:-...} と書いているので、API_URL が指定されていればそれを使い、無ければ同じ worktree の API を使います。フロントエンド側の worktree では、web だけを起動し、API_URL でバックエンド側の API を指定します。
# バックエンド側: DB あり、web と API を起動
./scripts/wt-new.sh feat-api
cd ../worktree-monorepo-lab.feat-api && pnpm dev
# フロントエンド側: DB は使わないので WT_DB=0。web だけを起動する
WT_DB=0 ./scripts/wt-new.sh feat-ui
cd ../worktree-monorepo-lab.feat-ui
API_URL=https://feat-api.api.monorepo-lab.localhost pnpm --filter web dev
試したところ、feat-ui の web から追加した TODO は feat-api の API と DB に入り、feat-api の web にも表示されました。
シェルで API_URL を export したままにすると、どの worktree の web もその API に接続します。指定はコマンドの先頭に付けて、そのコマンドだけに効かせます。
初回起動はグローバルな設定を変える
portless は初回起動時に、ローカル CA を作ってシステムの信頼ストアに登録します。さらに、既定では 443 番ポートを使うため sudo で権限を昇格します。どちらもマシン全体に影響する変更なので、自分で実行して確認しました。
sudo のパスワードを入力できない状況では、1355 番ポートで起動します。その場合 URL に :1355 が付きます。
DB: sashiki でブランチごとに分ける
アプリが手元の MySQL に接続している場合、worktree を分けても DB は共有のままです。sashiki は、baseline(元になる DB の状態)からブランチ用の MySQL を秒単位で作るツールです。macOS では、ここでも APFS の clonefile を使います。
- baseline のデータディレクトリを clonefile で複製し、ブランチごとに専用の mysqld を起動します
- 接続先は全ブランチ共通の 1 つのポート(この環境では 28306)で、ユーザー名の
@以降でどのブランチにつなぐかを決めます
wt-new.sh の最後で、sashiki があればブランチ用の DB を作り、接続先を worktree の .env.local に書きます。
export SASHIKI_DB_HOST=127.0.0.1 SASHIKI_DB_PASSWORD=dev
sashiki create --exist-ok "$db_branch"
sashiki env "$db_branch" --url-var DATABASE_URL --db app --write "$dst/.env.local"
sashiki env --write は、.env.local の同じキーの行だけを置き換え、人が書いたほかの行は残します。書かれる内容は次のとおりです。
DB_HOST=127.0.0.1
DB_PORT=28306
DB_USER=dev@feat-a
DATABASE_URL=mysql://dev%40feat-a:dev@127.0.0.1:28306/app
ユーザー名の @ は %40 にエスケープされます。そのままだと、ドライバがホストとの区切りと読み違えるためです。この --url-var と --write は、今回の用途のために sashiki に足しました(sashiki の main に入っていて、次のリリースに含まれます)。
単一アプリでは、React Router の dev サーバーが .env と .env.local の両方を読むので、worktree ごとに接続先が切り替わります。
モノレポでは、DATABASE_URL をルートの .env.local に書き、API が起動時にルートの .env.local → .env の順に読みます。process.loadEnvFile はすでに設定されている環境変数を上書きしないので、先に読んだ .env.local が優先されます。
const root = resolve(import.meta.dirname, "../../..");
for (const f of [".env.local", ".env"]) {
const p = resolve(root, f);
if (existsSync(p)) process.loadEnvFile(p);
}
どちらの構成でも、A で追加した TODO は A にだけ、B で追加したものは B にだけ表示されました。
.env.local は .gitignore に入れておく必要があります。git 管理外の未追跡ファイルがあると、git worktree remove が --force なしでは消せなくなるためです。
DB は clonefile でも 1 つ約 113MB 増える
node_modules の複製はほぼ容量を使いませんが、DB は 1 つ約 113MB 増えました。CoW の図で言うと、mysqld が起動時にたくさんのブロックに書き込むからです。redo log、undo tablespace、ibtmp1 などが新しく書かれ、その分は共有されません。
問題: ポートの衝突で別の worktree の API に接続する
portless は、dev サーバーのポートを 4000〜4999 番からランダムに選びます。選んだ候補で一度 listen して空いていることを確かめ、閉じてから、そのポート番号を dev サーバーに渡します。dev サーバーはあらためてそのポートで listen します。
TOCTOU の競合状態
この「確認してから使う」流れには、確認と使用の間に別のプロセスが同じポートを使うと衝突する、TOCTOU(time-of-check to time-of-use)の競合状態があります。2 つの dev サーバーを同時に起動し、たまたま同じ候補を引くと、次のようになります。
portless 0.15.12 で、Math.random を差し替えて 2 つに同じ候補を引かせると、両方に同じポートが渡り、後の方が EADDRINUSE になりました。衝突が起きうるのは、確認してから dev サーバーが bind するまでの間です。この間は一瞬ではなく、dev サーバーの起動時間まるごとです。起動に何秒もかかるアプリをいくつも同時に起動すると、衝突は珍しくありません。issue #533 には、ほかの利用者から次の実測が報告されています(8 つを並列に起動)。
| bind までの時間 | 衝突した回数 |
|---|---|
| 0 秒 | 200 回中 0 回 |
| 3 秒 | 20 回中 1 回 |
| 8 秒 | 12 回中 1 回 |
| 15 秒 | 12 回中 2 回 |
turbo で 8 アプリのモノレポを起動したところ、4 回続けて衝突したという報告もあります。この競合状態は、portless の現行版(0.15.13)では解決していません。修正の PR(#541)は出ていますが、まだマージされていません。
衝突すると何が起きるか
衝突したときの挙動は、dev サーバーによって違います。
| dev サーバー | 衝突したとき |
|---|---|
| Vite(React Router) | portless が --strictPort を付けて起動するので、Vite がエラーで終了する |
tsx watch | bind に失敗しても変更待ちで動き続ける。portless のルートが残り、エラーにならずに別の worktree のアプリに接続する |
tsx watch の場合を順に示します。検証中に、2 つの worktree の API に同じポートが割り当てられたとき、実際にこの状態になりました。
https://wt-test-a.api.monorepo-lab.localhost -> localhost:4138
https://wt-test-b.api.monorepo-lab.localhost -> localhost:4138
B の web は A の API を呼び、A の DB を読み書きしていました。 画面にもログにもエラーは出ません。エージェントを並行で走らせている場面なら、B のエージェントが A のエージェントの DB を書き換えることになります。
単一アプリ版は Vite だけなので、衝突しても起動に失敗するだけで済みます。node --watch や nodemon も、クラッシュ後に変更待ちに入る点は tsx watch と同じなので、同じ問題が起きるはずです(こちらは試していません)。
対策: bind に失敗したら親ごと止める
API で bind の失敗を受け取ったら、親の tsx watch ごと止めるようにしました。portless の子プロセスが終了するので、portless もルートを外して終了します。
server.on("error", (err: NodeJS.ErrnoException) => {
console.error(`api: ${port} 番を使えない(${err.code})。dev を止める`);
if (process.env.PORTLESS_URL) process.kill(process.ppid, "SIGTERM");
process.exit(1);
});
わざと衝突させて確かめました。127.0.0.1:4777 を別プロセスで使用中にし、PORTLESS_APP_PORT=4777 で API を起動すると、API が止まり(exit=1)、portless のルートも tsx watch のプロセスも残りませんでした。
これはエラーで止まるようにするだけで、衝突そのものは防げません。止まったらもう一度起動すれば、別のポートが選ばれます。
何本まで増やせるか
「無限に」と言っても、実際には上限があります。モノレポ(web と API)の worktree を 1 つ起動して、使う資源を測りました。
| 資源 | worktree 1 つあたり | 上限を決めるもの |
|---|---|---|
| メモリ(dev サーバー一式) | 約 790MB | pnpm と portless のラッパー、tsx、Vite(esbuild を含む)の RSS の合計 |
| メモリ(mysqld) | 約 130MB | sashiki のブランチ 1 つ |
| ディスク | 約 113MB | ほぼ DB の分。node_modules はほぼ 0 |
| ポート | 2 つ | portless の割り当て範囲は 4000〜4999 の 1000 個 |
| DB のブランチ数 | 1 つ | sashiki の設定 max_branches(この環境では 20) |
RSS(プロセスが使っている物理メモリ)の合計は、複数のプロセスで共有しているページを重複して数えるので、実際の使用量はこれより少なめです。それでも目安として、1 本あたり約 0.9GB です。64GB の Mac で、OS やエディタ、エージェント本体の分を差し引くと、数十本が現実的な上限です。
先に上限に達しやすいのは、メモリよりも設定の上限です。sashiki の max_branches はこの環境では 20 なので、それ以上並べるなら設定を上げます。DB を使わない作業なら WT_DB=0 で作れば、DB の分の資源は要りません。
また、dev サーバーは常に動かしておく必要はありません。エージェントが動作を確かめるときだけ npm run dev で起動し、終わったら止めれば、同時に動くのは確認中の数本だけになります。
実測
macOS 26.5.1 です。node_modules は単一アプリが 125MB、モノレポのルートが 132MB です。
| 項目 | 単一アプリ(npm) | モノレポ(pnpm) |
|---|---|---|
wt-new.sh の作成時間 | 2.4〜3.3 秒 | 3.2〜4.7 秒 |
| install | ロックファイルが同じなら走らない。差分 1 パッケージで 0.6 秒 | 同じく走らない。差分 1 パッケージで 0.4 秒 |
| URL | 2 つとも 200 | web・api の 4 つとも 200 |
作成時間の大半は sashiki の DB 作成です。
| 項目 | 結果 |
|---|---|
| node_modules の複製(clonefile) | 1.2 秒。空き容量の差は ±6MB で、何もしないときの変動と同程度 |
node_modules の複製(cp -R) | 3.6 秒。125MB を消費する |
| sashiki のブランチ 1 つ | 約 113MB |
ディスクの消費は、前述のとおり du ではなく df の空き容量の差で見ています。
macOS で起きたその他の問題
pgrep に -E が無い
Linux の pgrep に合わせて pgrep -f -E と書いたら、macOS では illegal option -- E で落ちました。macOS の pgrep は最初から拡張正規表現で解釈するので、-E は不要です。
bash 3.2 で "$dst(" が unbound になる
macOS の /usr/bin/env bash は、標準では bash 3.2 です。次の行が dst�: unbound variable で落ちました。
echo "[wt-rm] removed: $dst(ブランチ $branch は残している)"
bash 3.2 は、変数名の直後に全角文字があると、そのバイト列を変数名の一部として読みます。set -u なので、存在しない変数として止まります。${dst} のように波括弧で囲むと直ります。
日本語のメッセージを書くシェルスクリプトでは、変数の直後に全角文字が来る箇所を全部 ${…} にしておくのが安全です。
sashiki env のホスト名が解決できない
sashiki env は DB_HOST=sashiki.local を返しますが、この名前は解決できませんでした。手元ではプロキシが 127.0.0.1 で listen しているので、127.0.0.1 で接続しています。
既存の worktree ツールと組み合わせる
worktree を作って node_modules などを CoW で複製する部分は、既存のツールにもあります。たとえば次の 2 つは、作成後に任意のコマンドを実行できます(README で確認した範囲)。
| ツール | CoW での複製 | 作成後のコマンド |
|---|---|---|
| wtx(旧 wt-cli) | APFS・btrfs・XFS では reflink で複製し、それ以外は通常のコピーにする | .worktree.yml の setup。WTX_BRANCH_NAME などの環境変数が渡る |
| rabi(旧 phantom) | README からは確認できなかった | 作成後と削除前の hook |
アプリごとに違うのは、DB と URL の部分です。既存のツールを使う場合も、作成後のコマンドから sashiki create と sashiki env --write を呼べば、ブランチ用の DB の接続先を worktree の .env.local に書けます。URL は、各アプリの dev スクリプトを portless run 経由にするだけです。
使い終わったら
./scripts/wt-rm.sh feat-a
未コミットの変更がある worktree では git worktree remove がエラーになるので、--force は付けていません。エージェントの作業を誤って消さないためです。git のブランチも消しません。消すかどうかは人間が決めます。
まとめ
- エージェントを並行で走らせる単位は git worktree。worktree は
.gitを共有したまま作業ディレクトリだけを増やすが、ソースコード以外(node_modules、.env、URL、Cookie、DB)は自分で分ける - node_modules は CoW(clonefile)で複製すれば、時間もディスクもほぼかからない。書き込んだブロックだけが分かれるので、worktree 同士は独立している。pnpm のモノレポでもそのまま使える
- Cookie はポートを区別しないので、portless でサブドメインを分ける。エージェントごとに固定の URL ができる。モノレポではアプリ名を明示し、
portless getで同じ worktree の API の URL を取得する - DB は sashiki で分けられる。1 つ約 100MB 強のディスクと約 130MB のメモリを使う
- 上限は主にメモリと sashiki の
max_branchesで決まる。dev サーバーを確かめるときだけ起動すれば、本数はさらに増やせる - portless のポート割り当てには TOCTOU の競合状態があり、同時起動では衝突しうる。衝突すると、並行するエージェント同士が互いの API と DB に接続しうるので、bind に失敗した dev サーバーが動き続けないようにする