Claude Code ガイド

Appearance

原文（日本語に翻訳） ​

Claude が管理するワークツリーは、エージェントが終了したときにアンロックされたままになるようになりました。これにより git worktree remove / prune でクリーンアップできます。

原文（英語） ​

Worktrees managed by Claude are now left unlocked when the agent finishes, so git worktree remove/prune can clean them up

概要 ​

これまで Claude が管理するワークツリーはエージェント終了後もロックされた状態のままになることがあり、git worktree remove や git worktree prune による手動クリーンアップが阻害される問題がありました。v2.1.157 からはエージェントが終了するとワークツリーが確実にアンロックされるようになり、標準的な Git コマンドで不要なワークツリーを適切にクリーンアップできるようになりました。並列エージェントを多用する開発環境でのリソース管理が改善されます。

基本的な使い方 ​

エージェントが終了した後、通常の git worktree コマンドでクリーンアップできます。

bash
# 現在のワークツリー一覧を確認
git worktree list

# 特定のワークツリーを削除
git worktree remove .worktrees/feature-auth

# 存在しなくなったワークツリーの参照を一括クリーンアップ
git worktree prune

実践例 ​

エージェント完了後の手動クリーンアップ ​

bash
# Claude エージェントが feature/payment ブランチで作業を完了

# ワークツリー一覧を確認
git worktree list
# main          /home/user/my-project
# feature/auth  /home/user/my-project/.worktrees/feature-auth
# feature/pay   /home/user/my-project/.worktrees/feature-pay  [エージェント終了済み]

# 不要なワークツリーを削除（v2.1.157 以降はロックされていないので成功する）
git worktree remove .worktrees/feature-pay

# 確認
git worktree list
# main          /home/user/my-project
# feature/auth  /home/user/my-project/.worktrees/feature-auth

git worktree prune による一括クリーンアップ ​

bash
# 複数のエージェントが並列で作業を完了した後
git worktree list
# main                    /home/user/project
# .worktrees/agent-task1  /home/user/project/.worktrees/agent-task1
# .worktrees/agent-task2  /home/user/project/.worktrees/agent-task2
# .worktrees/agent-task3  /home/user/project/.worktrees/agent-task3

# 全エージェントが終了後、一括で古いワークツリーを削除
git worktree prune --verbose
# Removing worktrees/agent-task1: gitdir file points to non-existent location
# Removing worktrees/agent-task2: gitdir file points to non-existent location
# Removing worktrees/agent-task3: gitdir file points to non-existent location

CI/CD パイプラインでのクリーンアップ自動化 ​

bash
#!/bin/bash
# cleanup-worktrees.sh

# Claude エージェントによる並列処理が完了した後のクリーンアップスクリプト

echo "=== Claude ワークツリーのクリーンアップ ==="

# 古いワークツリーを prune
git worktree prune

# 削除可能なワークツリーを削除（変更なし・コミットなし）
git worktree list --porcelain | grep "worktree" | grep ".worktrees/" | while read -r _ path; do
  if git -C "$path" status --porcelain | grep -q '^'; then
    echo "変更あり、スキップ: $path"
  else
    echo "削除: $path"
    git worktree remove "$path"
  fi
done

echo "クリーンアップ完了"

--force オプションで強制削除（必要な場合） ​

bash
# ワークツリーが何らかの理由でまだロックされている場合（v2.1.157 以降は通常不要）
git worktree remove --force .worktrees/stale-worktree

# または prune に --expire を指定して古いものを対象にする
git worktree prune --expire=1.day.ago

注意点 ​

  • エージェントが終了してもワークツリーに未コミットの変更がある場合、git worktree remove は失敗します。その場合は --force オプションを使用するか、変更を確認してからコミット・廃棄してください。
  • git worktree prune は存在しなくなったディレクトリへの参照をクリーンアップするものです。ディレクトリが残っている場合は git worktree remove が必要です。
  • ワークツリー管理の設定を変更すると repositoryformatversion=1 や worktreeConfig=true が .git/config に残る場合があります。他の IDE や AI エージェントとの互換性に影響することがあるため、注意してください（GitHub Issue #45645）。
  • git worktree remove と git worktree prune は git 2.5 以降で利用可能です。

関連情報 ​