壁紙アプリの Android 版で、小さな不具合を直すためのブランチを手元で切ってから Desktop の Code タブを開いた日のことです。修正自体は数行で終わったのに、ビルドを頼むと設定ファイルが見つからないというエラーで止まりました。
ファイルは確かに手元にありました——少なくとも、私が見ているフォルダには。しばらく画面を見比べてようやく、セッションが自分のブランチではなく .claude/worktrees/ の下に作られた別のチェックアウトで動いていると気づきました。.gitignore に入れていた設定ファイルは、そちらには最初から存在しなかったのです。
同じ戸惑いは、Claude Code の Issue でも「新しいセッションが毎回 Worktree にチェックが入った状態で始まる」という形で報告されています(#110975、11月18日時点で未解決)。一方で公式ドキュメントは「Worktree は既定でオフ」と書いています。このずれを、私が辿った順にお伝えします。
worktree が作られたと言える3つの痕跡
最初に、本当に worktree で動いているのかを確かめます。思い込みで設定をいじり始めると、私のように遠回りになります。
- プロジェクトの直下に、
.claude/worktrees/<名前>/というフォルダが増えています git branchに、自分で作った覚えのないclaude/などで始まるブランチが並んでいます(Settings の Branch prefix で接頭辞を付けていれば、その名前です)- セッションの中で
pwdを実行すると、.claude/worktrees/を含むパスが返ります
三つ目がいちばん確実です。Desktop のターミナルペインか、セッションに「pwd と git branch --show-current を実行して」と頼むだけで分かります。
# いまのセッションが worktree の中かどうかを1行で判定する
[ "$(git rev-parse --absolute-git-dir)" = "$(git rev-parse --path-format=absolute --git-common-dir)" ] \
&& echo "本体のチェックアウトです" || echo "worktree の中です: $(git rev-parse --show-toplevel)"worktree では、自分専用の .git ディレクトリと、本体と共有する .git が別の場所になります。この二つを比べると、フォルダ名に頼らずに判定できます。
既定はオフなのに毎回オンになる — 確かめる3か所
ドキュメント上、Worktree はセッションを始める前に選ぶ項目で、既定はオフです。それでも毎回オンになるなら、どこかに「オンを既定にする設定」が残っています。私は次の順で探しました。
| 順番 | 見る場所 | オンになる理由 | 直し方 |
|---|---|---|---|
| 1 | プロンプト欄の下の行(現行レイアウト) | Worktree ボタンがオンのまま、そのセッションを始めている | 送信前にボタンをオフにする(始まったあとは切り替えられません) |
| 2 | 環境セレクタの保存済み環境(歯車アイコン) | 保存済みのローカル/SSH 環境に Worktree の既定が記録されている | 環境を編集して Worktree をオフにする、または別の環境から始める |
| 3 | ブランチ名の横のチェックボックス(以前のレイアウト) | 環境セレクタが無い旧レイアウトでは、ここが Worktree の切り替え | チェックを外す。現行レイアウトへの切り替えも検討する |
私の場合は二つ目でした。以前、並行作業のために作った保存済み環境で Worktree をオンにしたまま、その環境からセッションを始めていたのです。一度決めた既定は、決めたことごと忘れてしまうものなのかもしれません。
見落としやすいのは、自分で作っていない保存済み環境です。ドキュメントによると、現行レイアウトで Code タブを初めて開いたとき、Desktop は直近1か月によく使ったフォルダから最大8つの環境を自動で作ります。セレクタに見覚えのない環境が並んでいたら、歯車アイコンから中身を一度確かめてみてください。
なお、Issue #110975 が求めているのは「Worktree を使うかどうかの既定値を、設定として保存できるようにしてほしい」という機能です。保存済み環境ごとの既定はすでにありますが、すべての新規セッションに効く全体設定は、11月21日時点のドキュメントには見当たりませんでした。
作らせる場面と止める場面
worktree そのものは悪者ではありません。同じリポジトリで複数のセッションを並べるとき——たとえば修正とレビューを同時に回す日——互いの変更がぶつからないようにする仕組みです。困るのは、要らない場面で作られることだけでした。
| 場面 | Worktree | 理由 |
|---|---|---|
| 同じリポジトリで2つ以上のセッションを同時に走らせる | オン | 編集が同じファイルに重ならない |
| 結果が読めない試し書きを任せる | オン | 捨てるときに本体を汚さない |
| 自分で作業用ブランチを切ってから頼む | オフ | ブランチで隔離済み。worktree を足すとマージの手数が一つ増える |
| .env や local.properties など gitignore 済みのファイルがないと動かない | オフ、または .worktreeinclude を用意してからオン | worktree は新しいチェックアウトなので、追跡外のファイルは入っていない |
| SSH 先で、接続が途切れがちな回線から作業する | オフを検討 | worktree のセッションでは編集ごとに Desktop の確認が入り、切断中は失敗することがある |
隔離は一か所で十分です。ブランチで分けたなら、worktree はいりません。 私はいま、この線を守るようにしています。逆に、ブランチを切らずに頼む日は worktree に任せたほうが、あとで本体を片づける手間が減りました。
gitignore 済みのファイルを worktree に持ち込みたいときは、プロジェクトの直下に .worktreeinclude を置きます。書き方は .gitignore と同じで、パターンに合い、かつ gitignore されているファイルだけがコピーされます。
.env
.env.local
local.properties作らせたままでも気づけるように、SessionStart フックで知らせる
オンとオフを毎回選び分けても、うっかりは起きます。そこで、worktree の中でセッションが始まったときだけ、画面に一行出すフックを足しました。何を解決するかというと、冒頭の私のように「なぜかファイルが無い」と悩む時間をなくすことです。
#!/usr/bin/env python3
"""SessionStart フック: worktree の中で始まったセッションだけ、利用者と Claude に知らせる。"""
import json
import os
import subprocess
import sys
def git(cwd, *args):
r = subprocess.run(["git", "-C", cwd, *args], capture_output=True, text=True)
return r.stdout.strip() if r.returncode == 0 else ""
def main():
try:
data = json.load(sys.stdin)
except json.JSONDecodeError:
return 0 # 入力が読めなくてもセッションは止めない
# Desktop の worktree セッションではフックが本体側のルートで動くため、
# os.getcwd() や CLAUDE_PROJECT_DIR ではなく入力の cwd を見る
cwd = data.get("cwd") or os.getcwd()
git_dir = git(cwd, "rev-parse", "--absolute-git-dir")
common = git(cwd, "rev-parse", "--path-format=absolute", "--git-common-dir")
if not git_dir or git_dir == common:
return 0 # git 管理外、または本体のチェックアウト: 何も出さない
top = git(cwd, "rev-parse", "--show-toplevel")
branch = git(cwd, "branch", "--show-current") or "(detached)"
main_root = os.path.dirname(common)
missing = [f for f in (".env", ".env.local", "local.properties")
if os.path.exists(os.path.join(main_root, f))
and not os.path.exists(os.path.join(top, f))]
msg = f"worktree で動いています: {top}(ブランチ {branch})"
if missing:
msg += f"/本体にあってここに無いファイル: {', '.join(missing)}(.worktreeinclude を確認)"
print(json.dumps({
"systemMessage": msg,
"hookSpecificOutput": {
"hookEventName": "SessionStart",
"additionalContext": msg + "。ビルドやテストが失敗したら、まずこの差を疑ってください。",
},
}, ensure_ascii=False))
return 0
if __name__ == "__main__":
sys.exit(main())このファイルを .claude/hooks/worktree-notice.py として置き、プロジェクトの .claude/settings.json に登録します。
{
"hooks": {
"SessionStart": [
{
"matcher": "startup",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/worktree-notice.py\""
}
]
}
]
}
}なぜこう書くのか、要点は三つです。
- 入力の
cwdを見る: Desktop から始めた worktree セッションでは、フックは本体のチェックアウトのルートで動き、CLAUDE_PROJECT_DIRもそちらを指します。作業中の worktree の場所は、フックに渡される JSON のcwdにしか入っていません。ここをos.getcwd()にすると、いつも「本体です」と判定してしまいます systemMessageとadditionalContextを両方返す: 前者は画面に出る一行、後者は Claude が最初の返答の前に読む文脈です。人と Claude の両方が同じ前提に立てます- 失敗しても黙って終わる: git 管理外のフォルダや入力の崩れでは何も出さず、終了コード 0 で抜けます。知らせるためのフックがセッションを止めては本末転倒です
手元の git 2.34.1 で、worktree の中・本体・git 管理外の3通りを JSON で流して確かめました。worktree の中でだけ一行が返り、本体に .env があって worktree に無い場合はその名前も添えられます。
それでも直らないときの次の一手
ここまでで毎回オンになる原因が見つからない場合、次の順で手を打ちます。
- CLI から始める: ターミナルで
claudeを起動すると、--worktree(-w)を付けない限り worktree は作られません。急ぎの作業は、こちらに逃がすのがいちばん確実でした - Issue #110975 に状況を添える: 環境の種類(ローカル/SSH)、レイアウト、保存済み環境を使っているかを書き添えると、再現の手がかりになります。👍 だけでも優先度の判断材料になります
- 作られてしまった worktree はアーカイブで片づける: コミットしていない変更は、アーカイブのときに失われることがあります。残したいものを先にコミットしてから、サイドバーのメニューで Archive を選びます。ローカルのセッションなら、変更が残った worktree もおよそ30日後に Desktop が取り除きます
溜まった worktree をまとめて棚卸ししたい場合は、消す前に何が残っているかを読み取り専用で数える手順を 消えたことになっている作業ツリーの棚卸しと、隔離の任せどころ に書き残しています。並列で走らせる側の設計は Claude Code を worktree ごとに走らせる並列開発の実装メモ が入口になると思います。
次に Desktop で新しいセッションを始めるときは、送信する前にプロンプト欄の下の行を一度だけ見て、Worktree がオンなら「いまこのセッションに隔離は要るか」を自分に尋ねてみてください。私もその一呼吸を挟むようになってから、見覚えのないブランチを消す夜がなくなりました。