技術ブログ

Hermes AgentをGit worktreeで分離する｜並列編集を同じ作業フォルダで走らせない

約13分で読めます
#Hermes Agent#AIエージェント#Git#Worktree
Hermes AgentをGit worktreeで分離する｜並列編集を同じ作業フォルダで走らせない

同じリポジトリで 2 体の AI エージェントを走らせても、会話は混ざりません。しかし、作業フォルダが同じならファイル変更は混ざります。片方がpackage.jsonを書き換え、もう片方が古い前提でテストする状況は普通に起きます。

私は、並列編集の境界をプロンプトだけに任せません。Git worktree で「1 体につき 1 ブランチ、1 作業フォルダ」を割り当てます。2026 年 9 月 3 日に Hermes Agent v0.20.6 と Git 2.47.3 で分離を試し、親側のファイルが変わらないことまで確認しました。

前回から今回への差分

前回のHermes Agentのサブエージェント設計では、親と子の会話を分け、調査結果だけを親へ戻しました。今回は、会話だけでなく Git の編集場所も分けます。

前回完了時今回完了後
子ごとに会話の文脈が分かれます子ごとにブランチと作業フォルダも分かれます
同じworktreeへの並列書き込みが残ります片方の未commit変更がもう片方へ見えません
衝突は編集後に発見します編集前に分離し、統合時に差分を確認します

hermes -wをすでに使っている場合は、「2 つの worktree が本当に分かれるか試す」まで飛ばせます。手動管理をしない場合は、「汚れた worktree は削除できない」も読み飛ばせます。

なぜプロンプトの担当分けだけでは足りないのか

「A は API、B は画面だけを変更する」と指示しても、境界は曖昧です。API の型を直せば、画面側の生成コードも変えたくなります。formatter や lockfile 更新は担当外のファイルへ広がります。

Git worktree は、1 つの repository から複数の working tree を作る Git の機能です。各 worktree は別のHEADと index を持ちます。一方、object database や refs は repository 内で共有します。repository 一式を 2 回 clone するより軽く、変更の所属は branch で追えます。

Hermes Agent は起動した現在ディレクトリを project root として扱います。そのため、Hermes のセッションごとに別 worktree を割り当てれば、file tool と terminal tool の書き込み先も分かれます。

用語表

用語ここでの意味
main worktree最初にcloneした通常の作業フォルダです
linked worktreegit worktree addで追加した作業フォルダです
index次のcommitへ入れる変更をGitが管理する領域です。worktreeごとに分かれます
refbranchなどの参照です。通常のbranch refはworktree間で共有します
hermes -wHermesが一時worktreeとbranchを作り、その中でセッションを始める起動方法です
checkpointHermesが破壊的操作の前に作る任意のsnapshotです。Git worktreeとは別の安全層です

編集の境界はこうなる

同じGit repository
├── main worktree
│   ├── branch: main
│   └── Hermes Aのfile / terminal tool
│
└── linked worktree
    ├── branch: feature/agent-a
    └── Hermes Bのfile / terminal tool

共有: commit object、通常のbranch ref
分離: HEAD、index、未commitのファイル変更、Hermesのcheckpoint履歴

未 commit の変更は、別 worktree へ自動で現れません。commit 後の branch は repository 全体から参照できます。最後は親役が branch の diff を読み、必要な変更だけを merge します。

最短ならhermes -wで起動する

Hermes Agent の公式ガイドでは、-wまたは--worktreeを最短経路として案内しています。repository の root で起動します。

cd /path/to/your/repository
hermes -w

2026 年 9 月 3 日のhermes --helpでは、該当行を次のように確認できました。

--worktree, -w        Run in an isolated git worktree (for parallel agents)

Hermes は repository 内の.worktrees/に一時 worktree を作り、hermes/hermes-に hash を続けた branch を割り当てます。interactive セッション内なら、/worktree new my-experimentでも作成できます。この場合は.worktrees/my-experiment/とhermes/my-experimentbranch が使われます。

複数の terminal でhermes -wを 1 回ずつ起動すると、それぞれ別 worktree になります。ただし、分離は merge の自動化ではありません。各 branch の commit、diff、test を読んでから統合します。

サブエージェントの編集も分ける

delegate_taskの子が Git を編集する運用では、delegation.worktree_isolationを有効にできます。設定変更にはconfig.yamlの手編集ではなく CLI を使います。

hermes config set delegation.worktree_isolation true

有効時の子は、.worktrees/subagent-に ID を続けた directory と、hermes-subagent/subagent-に同じ ID を続けた branch を使います。clean で commit が無い worktree は終了時に自動削除されます。commit または未 commit 変更が残る worktree は、確認できるよう保持されます。

この機能は Git repository かつ local terminal backend 向けです。Docker、SSH、Modal などでは同じ分離を前提にしません。親側で子の返したworktree.path、branch、commits、dirtyを読み、保存された仕事の有無を判断します。

2つのworktreeが本当に分かれるか試す

Hermes を 2 体起動する前に、Git だけで境界を確認できます。次の操作は/tmpに小さな repository を作ります。既存 project は変更しません。

mkdir -p /tmp/hermes-worktree-demo
git init -b main /tmp/hermes-worktree-demo
printf 'main\n' > /tmp/hermes-worktree-demo/state.txt
git -C /tmp/hermes-worktree-demo add state.txt
git -C /tmp/hermes-worktree-demo \
  -c user.name='Hermes Demo' \
  -c user.email='[email protected]' \
  commit -m 'init'

git -C /tmp/hermes-worktree-demo worktree add \
  -b feature/agent-a \
  /tmp/hermes-worktree-demo-feature

実行時は、初回 commit と worktree 作成が成功しました。

Initialized empty Git repository in /tmp/hermes-worktree-demo/.git/
[main (root-commit) 6869599] init
 1 file changed, 1 insertion(+)
 create mode 100644 state.txt
Preparing worktree (new branch 'feature/agent-a')
HEAD is now at 6869599 init

linked worktree 側だけを書き換えます。

printf 'agent-a\n' > /tmp/hermes-worktree-demo-feature/state.txt

git -C /tmp/hermes-worktree-demo status --short
cat /tmp/hermes-worktree-demo/state.txt

git -C /tmp/hermes-worktree-demo-feature status --short
cat /tmp/hermes-worktree-demo-feature/state.txt

結果は次のとおりです。main 側のstatus --shortは空で、ファイルもmainのままでした。linked worktree 側だけに変更が出ています。

main
 M state.txt
agent-a

worktree と branch の対応も確認します。

git -C /tmp/hermes-worktree-demo worktree list
/tmp/hermes-worktree-demo          6869599 [main]
/tmp/hermes-worktree-demo-feature  6869599 [feature/agent-a]

ここまで確認できれば、Hermes A を main worktree、Hermes B を linked worktree で動かしても、未 commit 変更は交差しません。

汚れたworktreeは削除できない

作業後は、残す変更を commit または破棄したうえで worktree を削除します。Git は未 commit 変更がある worktree の通常削除を拒否します。

git -C /tmp/hermes-worktree-demo worktree remove \
  /tmp/hermes-worktree-demo-feature

今回の実行では exit code 128 になりました。

fatal: '/tmp/hermes-worktree-demo-feature' contains modified or untracked files, use --force to delete it

この拒否は安全装置です。AI エージェントの変更が残っている場面で、反射的に--forceを付けるべきではありません。先に次を読みます。

git -C /tmp/hermes-worktree-demo-feature status --short
git -C /tmp/hermes-worktree-demo-feature diff

今回の demo では変更が不要だと確認し、git restore state.txtで戻してから削除しました。削除後の一覧には main だけが残りました。

/tmp/hermes-worktree-demo 6869599 [main]

よくあるエラー

症状原因対処
is already checked out同じbranchを別worktreeが使用しています新しいbranch名を使い、git worktree listで所有者を確認します
contains modified or untracked files未commit変更が残っていますstatusとdiffを読み、commitまたは意図した復元後に削除します
子の変更が親のfolderへ出ますworktree分離が無効か、local Git環境ではありません子のworktree.pathと親の現在ディレクトリを確認します
worktreeのfolderだけ消えて一覧に残りますGitを通さずdirectoryを削除しましたgit worktree prune --dry-runで対象を確認してからpruneします
2つのbranchは単独でtest成功するのにmerge後に失敗します分離は統合後の互換性を保証しませんmerge後のbranchでtestとbuildを再実行します

worktreeとcheckpointは役割が違う

worktree は並列作業を分けます。checkpoint は、同じ作業中の破壊的変更から戻るための snapshot です。Hermes の checkpoint は任意機能で、デフォルトでは無効です。使う場合も、worktree の branch と commit に置き換わるものではありません。

私は境界を次の順で置きます。

  • worktree でエージェント同士の未 commit 変更を分けます
  • branch と commit で採用する変更を固定します
  • checkpoint で作業途中の誤操作に戻り道を作ります
  • merge 後に test と build をやり直します

AI エージェントを増やすと、速さより先に変更の所有者が見えにくくなります。hermes -wは、その問題を Git の既存機能へ寄せる小さな入口です。別 folder、別 branch、統合時の再検証。この 3 点を守れば、並列化しても差分を人が追えます。

一次情報

資料確認した内容
Hermes Agent公式ドキュメント: Git Worktreeshermes -w、/worktree new、worktreeごとのproject rootとcheckpoint分離
Hermes Agent公式ドキュメント: Subagent Delegationdelegation.worktree_isolationの動作、保持と自動削除の条件、対応範囲
Hermes Agent公式ドキュメント: Checkpoints and rollbackcheckpointが任意機能であること、worktreeとの役割の違い
Git公式リファレンス: git-worktreelinked worktree、共有ref、add、list、remove、pruneの仕様
この記事をシェア
hibana
この記事を書いた人
hibana

技術ブログを運営しています。日々の学びや発見を発信中。

関連記事