Claude Codeの--refフラグでセルフホスト環境の起点ブランチを指定する
claude --environmentで作るセルフホスト環境セッションを、ローカルHEADでなく--refで指定したブランチから起動する方法と、併用できないフラグ、ローカルの--worktreeとの違いをまとめました。
--refは、--environmentで作るセルフホスト環境のセッションを、ローカルのHEADではなく指定したブランチから起動するCLIフラグです。フラグの書式は--ref <branch>で、値には具体的なブランチ名を渡します。単独では働かず、必ず--environmentと組み合わせます。要求バージョンはClaude Code v2.1.224以降で、--environment自体と同じ条件です。
--refが解決する問題
--environmentだけを渡した場合、セッションは実行したディレクトリのローカルHEADをチェックアウトします。手元の作業ブランチと、セルフホスト環境で動かしたいブランチが一致しない場面では、事前にgit checkoutで切り替えるか、--refで明示的に指定するかのどちらかが必要です。
典型的なのは、CIホストや自分の作業マシンをmainブランチに置いたまま、リリース候補ブランチやPRブランチに対してセッションをディスパッチしたい場合です。ローカルの作業状態を動かさずに済みます。セルフホスト環境そのものの仕組み(Environment・Runner・Sessionの3要素)はClaude Code self-hosted-runnerとはで扱っているので、初めて触る場合はそちらを先に読むと以降の説明が早く飲み込めます。
使い方の基本形
--refには具体的なブランチ名を渡します。--environmentにはセルフホスト環境のID(ccpool_で始まる)が必須です。--refは--environmentとの組み合わせでのみ公式ドキュメントに記載されており、--cloud単体で新規セッションを作るときにこのフラグを渡す使い方は文書化されていません。
なお、--environmentと--refはセッションを作る側(開発者やCIスクリプト)が使うフラグです。自社ホスト上でRunnerを起動・登録するのはclaude self-hosted-runnerという別のコマンドの役割で、両者は担当する場面がはっきり分かれています。
claude -p "smokeテストを実行して結果を返して" \
--environment ccpool_abc123 \
--ref release/2.4 \
--output-format jsonこのコマンドはgitチェックアウトの中で実行する必要があります。Claude Codeがoriginリモートからリポジトリを自動検出する仕組みだからです。チェックアウト外のディレクトリや、originリモートを持たないリポジトリでは自動検出ができません。実行するとセッションが作成され、session_idを含む1行のJSONを出力してすぐに終了します。応答を待つ動作ではないため、続きを読みたい場合はStop hookでの読み戻しやポーリングを別途組む必要があります。この読み戻しの実装はClaude CodeセルフホストのE2Eテストで詳しく扱っています。
--environmentに渡すID(ccpool_で始まる文字列)は、claude.aiの管理画面「Cloud environments」で対象のEnvironmentを開いた詳細ダイアログに表示されています。API応答のフィールド名やトークンのクレーム、メトリクス名の中では、このEnvironmentはpoolという語で表されることがあります。ccpool_というID自体もこの命名に由来しており、呼び方が違うだけで指しているものは同じEnvironmentです。
--refに渡すブランチは、Runnerがoriginリモートからクローンする対象のリポジトリに実在している必要があります。ローカルにしかない未pushのブランチを指定しても、Runner側のクローンには反映されません。また、ディスパッチしたセッションはEnvironment側のキューに入り、空いているRunnerが拾うまで待機します。コマンド自体はすぐ終了しますが、実際にセッションが動き出すまでには時間差が生じる点は覚えておく必要があります。
作成したセッションへの追加メッセージは--refではなく別のフラグ、--cloud <session-id>で送ります。--refが効くのはセッションを新規作成する瞬間だけです。
--environmentディスパッチで一緒に使えないフラグ
--environmentは新規セッションを作るためのフラグなので、既存セッションを再開・準備する系のフラグとは組み合わせられません。--refを使うときも同じ制約を受けます。
| 制約 | 内容 |
|---|---|
| 再開系フラグ | 内容--resume(-r)・--continue(-c)・--teleport・--session-id・--init-onlyとは併用不可 |
| 出力形式 | 内容--output-format stream-jsonは非対応。jsonかtextを使う |
--cloudとの併用 | 内容セッションIDやURLを渡す形の--cloudとは併用不可。非対話実行で説明文付きの--cloudを渡すのも不可(素の--cloudは無指定扱い) |
| 設定ファイルとの優先順位 | 内容--environmentは設定ファイルのremote.defaultEnvironmentIdより優先される |
つまり、動かしているセッションのブランチだけを後から--refで差し替えることはできません。ブランチを変えたいときは、新しいセッションを作り直すのが唯一の方法です。セルフホスト環境まわりの他のCLIフラグ(Runner側の--retire-atや--drain-grace-secなど)はClaude Codeセルフホスト環境のCLIフラグ・メトリクスリファレンスにまとめてあります。
ローカルの--worktreeとの違い
「ブランチを指定してセッションを始める」という点で紛らわしいのが、ローカルで動く--worktree(-w)です。両者は実行場所も、ブランチ指定の自由度もまったく別物です。
| 観点 | --environment + --ref | --worktree / -w |
|---|---|---|
| 実行場所 | --environment + --ref自社のセルフホスト環境(Runner) | --worktree / -wローカルマシン上のgit worktree |
| 任意のブランチ名を直接渡せるか | --environment + --ref渡せる(--ref <branch>) | --worktree / -w渡せない。設定worktree.baseRefは"fresh"(既定、リモートの既定ブランチ)か"head"(ローカルの現在のHEAD)の2値のみ |
| 特定ブランチから始める方法 | --environment + --ref--refに名前を渡すだけ | --worktree / -wgit worktree addで手動作成するか、PR番号やURL(#123等)を--worktreeに渡す |
| 向く用途 | --environment + --refCIやチームで共有するRunner上でのディスパッチ | --worktree / -w個人の手元での並列作業・サブエージェントの隔離 |
--worktreeはPR番号やGitHub/GitLabのURLを受け取って、そのPRのhead commitから直接ブランチを作れます。一方で任意の既存ブランチ名を指定するフラグは無く、公式ドキュメントも「特定の既存ブランチから始めたいならgitで直接作成する」ことを案内しています。ブランチ名をそのまま渡せる--refは、この点でローカルworktreeより柔軟です。ただし--refが効くのはセルフホスト環境のセッションに限られ、ローカルのclaude起動には影響しません。
言い換えると、ローカルの並列作業には--worktree、共有Runner上でのブランチ別ディスパッチには--refと、そもそも解決したい課題が違います。両方を同じ「ブランチ指定フラグ」として一括りにすると、片方の制約をもう片方にも当てはめてしまいがちです。
セルフホスト環境という利用条件
--refはセルフホスト環境がある組織でしか意味を持たないため、前提となる利用条件も押さえておく必要があります。
- プランと有効化: TeamプランとEnterpriseプランのパブリックベータで、既定では無効です。組織のOwnerが管理画面の「Cloud environments」ページで「Allow self-hosted environments」を有効にする必要があり、これには組織でClaude Code on the webが有効になっていることが前提条件になります
- Zero Data Retention: 有効にしている組織では使えません
- リポジトリ: セッションが直接チェックアウトできるのはGitHubリポジトリのみです。GitLabやBitbucketは対象外です
- 課金: セルフホスト環境上のセッションも、Anthropicホスト環境のセッションと同じ基準で組織のClaude Code利用枠を消費します
- 対応する起動経路: claude.aiのweb、モバイル・デスクトップアプリ、スケジュール実行のroutines、ターミナルの
--cloudまたは--environmentディスパッチがセルフホスト環境に対応しています。Claude Tagのチャンネルセッションも動きますが、Access bundlesはまだ使えません。Claude SecurityとCode Reviewのセッションはまだセルフホスト環境にルーティングされません
セルフホストを選ぶ組織の動機は、社内ネットワークへのアクセス、独自ツールの事前インストール、コンプライアンス上の理由でセッションの実行場所を自社管理下に置きたいケースです。--refによるブランチ指定は、その自社Runner上でリリース候補ブランチや長期稼働のPRブランチを検証したい場面でとくに効きます。
「セルフホスト環境」と「self-hosted-runner」という2つの語が指す範囲の違いに迷う場合は、self-hosted environmentsとself-hosted-runnerの違いが整理の助けになります。
よくあるつまずき
いずれも、--ref単体の不具合ではなく--environmentディスパッチ全体の制約に起因します。切り分けの参考にしてください。
- バージョンが古くてフラグが存在しない:
--environmentと--refはどちらもv2.1.224以降が必要です。claude --versionで確認し、古い場合はまずclaude updateから始めます - gitチェックアウトの外から実行してしまう: リポジトリは
originリモートから自動検出されるため、チェックアウト外のディレクトリやoriginが無いリポジトリでは失敗します - 走っているセッションのブランチを後から変えようとする:
--refが効くのは新規セッションの作成時だけです。--resumeや--continueと組み合わせても反映されません --cloudと混同する: 新規セッションの作成は--environment(+--ref)、既存セッションへの追記は--cloud <session-id>と、担当が分かれています- ローカルのブランチ切り替えと同じ感覚で使う:
--refはセルフホスト環境上のチェックアウトにしか作用しません。ローカルの作業ツリーやほかのclaude起動には一切影響しません - 認証が済んでいないホストから実行する: 非対話でセッションを作るには、そのマシンで事前に
claude auth loginを済ませておく必要があります。取得したリフレッシュトークンには初回ログインから30日の上限があるため、CI専用ホストでは定期的な再ログインが要ります
まとめ
--refは、セルフホスト環境向けの--environmentディスパッチに、ローカルHEAD以外のブランチを渡すための専用フラグです。単独では機能せず、要求バージョン(v2.1.224以降)・対応リポジトリ(GitHubのみ)・プラン要件(Team/Enterpriseベータ)という前提を満たして初めて使えます。ローカルの--worktreeとは実行場所もブランチ指定の自由度も別物なので、混同せずに使い分けます。
すでに動いているセッションのブランチを--refだけで後から変えることはできず、--resumeや--continueとの併用も不可です。ブランチを切り替えたいときは、そのつど新しいセッションを作り直す前提で運用します。