Claude Media
Claude DesktopのSSHでWorktreeの置き場所を決める設定
Claude CodeTips

Claude DesktopのSSHでWorktreeの置き場所を決める設定

Claude DesktopのSSHセッションでworktreeを作るフォルダは、接続のWorktree folder、リモートのworktree.location、既定の順で決まります。プロジェクト内を指すと無視される条件も押さえます。

読了目安 約10分

SSHセッションのworktreeは3段階の優先順位で置き場所が決まる

Claude DesktopのSSHセッションで新しいworktreeを作る場所は、次の3つのうち、最初に設定されているものが使われます。

  1. SSH接続に付けたWorktree folder
  2. リモートマシンの ~/.claude/settings.json にある worktree.location
  3. <project-root>/.claude/worktrees/(既定)

何も設定しなければ、worktreeはリモート側のプロジェクトの中に作られます。プロジェクトの外に逃がしたいときに、1か2を使います。

この優先順位は、組織がセッションで使えるフォルダを制限していない場合の話です。制限がある場合は、どちらの設定も効きません。詳しくは後半の「組織の制限があるとき」で扱います。

接続のWorktree folderを設定する

Desktopの接続設定には、SSHホストやポートと並んでWorktree folderの欄があります。リモートマシン上のフォルダを書く欄で、例として ~/worktrees が挙げられています。空のままにすると、リモートマシンの既定(次節の worktree.location か、プロジェクト内)に従います。

接続の追加時は、環境ドロップダウンからSSH > Add SSH connection… を開き、Name、SSH host、SSH port、SSH keyと並ぶ欄に入力します。

すでに追加した接続や、組織が配った接続に後から設定することもできます。環境ドロップダウンで接続にカーソルを合わせ、歯車アイコンをクリックします。

実際のパスはどうなるか

指定したフォルダの直下に、プロジェクトごとのサブフォルダが作られます。~/worktrees を指定した場合、worktreeのパスは次の形です。

~/worktrees/<project>-<id>/<worktree-name>

複数のリポジトリで同じ ~/worktrees を共有しても、プロジェクトごとにサブフォルダが分かれます。リポジトリごとに別のフォルダを用意する必要はありません。

プロジェクト内を指すと無視される

指定したフォルダがプロジェクトの内側にある場合、Desktopはそのプロジェクトについてその指定を無視し、既定の場所を使います。たとえばプロジェクトが ~/src/app のとき、~/src/app/tmp-worktrees を指定しても反映されません。

エラーで知らせる挙動は公式の説明に書かれていません。置き場所を変えたのに従来どおりプロジェクト内にworktreeができるときは、まず指定フォルダがプロジェクトの内側に入っていないかを確認します。

リモートのsettings.jsonでworktree.locationを決める

接続側の欄を空にしておき、リモートマシン側で場所を決める方法もあります。~/.claude/settings.json に worktree.location を書きます。

{
  "worktree": {
    "location": "~/worktrees"
  }
}
項目内容
スコープ内容User(リモートマシンの ~/.claude/settings.json)
型内容文字列。絶対パス、または ~/ で始まるパス
既定内容未設定。worktreeはプロジェクトの中に作られる
必要なバージョン内容Claude Desktop v1.44121.0以上

プロジェクトの設定ファイルには置けません。スコープがUserなので、設定する場所はリモートマシンの ~/.claude/settings.json です。

接続側の指定が優先される

両方を設定した場合は、接続のWorktree folderが勝ちます。たとえば共有の開発VMで、全員のsettings.jsonに ~/worktrees が入っている状況でも、特定の接続だけ別のフォルダに向けられます。

このキーはDesktopのSSHセッションだけに効く

worktree.location を読むのはデスクトップアプリだけです。次の経路は、このキーを無視します。

  • --worktree フラグ
  • EnterWorktree ツール
  • 分離された(isolated)サブエージェント
  • バックグラウンドセッション

リモートのsettings.jsonに書いても、ターミナルで claude --worktree を使う場合の置き場所は変わりません。同じリモートマシンで、Desktop経由とCLI経由のworktreeが別の場所にできる点に注意します。CLI側のworktreeの起点や範囲を決める設定はworktree.baseRefとsparsePathsで扱っています。こちらは置き場所ではなく、何を元にどこまで取り出すかの設定です。

組織の制限があるとき

組織がセッションで使えるフォルダを制限している場合、DesktopはWorktree folderの欄を隠し、worktreeをプロジェクトの中に置き続けます。worktree.location も同様で、制限が優先されます。

欄が見当たらないときの確認順は次のとおりです。

  1. Claude Desktopがv1.44121.0以上かを確認する(古いと欄自体がない)
  2. 歯車アイコンを出した画面に欄がないなら、組織の制限が掛かっている可能性を管理者に確認する

どの設定キーで制限しているのかは、確認できた公式の説明には書かれていません。欄が隠れる条件は「組織がフォルダを制限しているとき」と書かれているだけです。

管理者が配った接続でもユーザーは変えられる

管理者は sshConfigs をmanaged settingsに書いて、チームにSSH接続を配れます。配られた接続はドロップダウンに管理対象として表示され、ユーザーは削除も編集もできません。例外がWorktree folderで、ユーザーが自分で設定できます。

{
  "sshConfigs": [
    {
      "id": "shared-dev-vm",
      "name": "Shared Dev VM",
      "sshHost": "user@dev.example.com",
      "sshPort": 22,
      "sshIdentityFile": "~/.ssh/id_ed25519"
    }
  ]
}

したがって、共有VMの接続を配る管理者は、worktreeの置き場所までは接続定義に含められません。置き場所を揃えたいときは、各ユーザーに歯車アイコンから設定してもらうか、リモートの ~/.claude/settings.json に worktree.location を入れておく運用になります。接続先を許可ホストに絞る設定はsshHostAllowlistの解説にあります。

どこに置くのが向くか

置き場所を決める判断は、容量とクリーンアップのしやすさに寄ります。

状況向く設定理由
1人で使う個人VM向く設定既定のまま理由設定が要らず、プロジェクトの隣に残る
ディスクの大きい別ボリュームがある向く設定Worktree folderかworktree.locationでそこを指す理由プロジェクトのあるディスクを圧迫しない
複数人が同じVMを共有する向く設定各自の接続で別のWorktree folder理由ユーザーごとに置き場所を分けられる
Desktop以外でもリモートを使う向く設定場所の違いを許容する理由--worktree などは既定の場所に作る

判断の分かれ目は、worktreeを何本まで並べるかとディスクの余裕です。worktreeが何を主チェックアウトと共有するかはClaude Code Worktree実践ガイドに整理があります。

リンクのssh_folderはworktreeの置き場所ではない

claude://code/new のディープリンクには ssh_host、ssh_port、ssh_folder、q のパラメータがあります。このうち ssh_folder は、リモートマシン上の作業フォルダ(プロジェクト側)を指す値で、worktreeの置き場所ではありません。Worktree folderと名前が似ているので取り違えやすい点です。

名前指すもの設定する場所
ssh_folder指すものリンクで開くリモートのフォルダ設定する場所claude://code/new のURLパラメータ
Worktree folder指すものworktreeを作るフォルダ設定する場所SSH接続の設定欄
worktree.location指すものworktreeを作るフォルダ設定する場所リモートの ~/.claude/settings.json

SSHリンクを使うにはClaude Desktop v2.110.0以上が必要です。リンクはホストやフォルダの入力を省くためのもので、worktreeの置き場所は変わりません。リンクを開いても、接続の保存や選択は確認ダイアログで承認するまで行われません。

設定後の確認とクリーンアップ

設定が効いたかは、新しいSSHセッションを開始して、リモート側で実際のパスを見て確かめます。

# リモートマシン上で実行
cat ~/.claude/settings.json
git -C <project-root> worktree list
ls ~/worktrees

git worktree list の出力に、~/worktrees/<project>-<id>/<worktree-name> の形のパスが並べば、指定が反映されています。プロジェクト内のパスが出たなら、前節までの条件(プロジェクト内を指していないか、組織の制限がないか、バージョンは足りているか)を順に当たります。

既存のセッションのworktreeは、設定を変えても移動しません。変更が効くのは新しく作るworktreeです。

作ったworktreeを消すには、サイドバーでセッションにカーソルを合わせ、アーカイブのアイコンをクリックします。Auto-archive after PR merge or closeはローカルセッションの設定で、終了済みのローカルセッションにだけ適用されます。SSHセッションの後片付けは、サイドバーのアーカイブ操作で行います。

ローカルセッションの置き場所は別の設定

ローカルセッションでは、置き場所はSettings > Claude CodeのWorktree locationで変えます。SSHセッションのWorktree folderとは別の画面にある別の設定で、公式の説明では、SSHセッションの置き場所はSSH接続側の欄かリモートのsettings.jsonで決めます。同じ画面には、Desktopがworktreeのブランチ名の先頭に付けるBranch prefixもあります。

.gitignore された .env のようなファイルを新しいworktreeに持ち込みたいときは、プロジェクトのルートに .worktreeinclude を置きます。並列セッションそのものの使い方はClaude Code Desktopの並列セッションにまとめています。

よくあるつまずき

  • 欄が見つからない: Desktopのバージョンが古いか、組織がフォルダを制限しています。v1.44121.0以上かを先に確認する
  • 指定したのにプロジェクト内にできる: 指定フォルダがプロジェクトの内側にある可能性があります。外側のパスに変える
  • settings.jsonに書いたのに変わらない: 接続側のWorktree folderが設定済みだと、そちらが優先されます。接続の歯車アイコンで空にする
  • CLIのworktreeだけ別の場所にできる: --worktree は worktree.location を読みません。仕様どおりの挙動です
  • SSHの接続自体が失敗する: worktreeの設定以前の問題です。WindowsでのSSH起動エラーはFailed to spawn /usr/bin/sshの対処で扱っています

リモートマシンはLinuxかmacOSである必要があり、Desktopは初回の接続時にClaude Codeをリモートへ自動でインストールします。worktreeを使うセッションにはGitが必要です。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →