Claude Codeの--refフラグでセルフホスト環境の起点ブランチを指定する

--refは、--environmentで作るセルフホスト環境のセッションを、ローカルのHEADではなく指定したブランチから起動するCLIフラグです。書式は--ref <branch>で、単独では働かず必ず--environmentと組み合わせます。要求バージョンはClaude Code v2.1.224以降で、--environment自体と同じです。

v2.1.289のclaude --helpには--environment <environment_id>の行(「Create a new cloud session that runs on the given self-hosted environment (ccpool_...)」)があります。一方で--refの行はありません。このフラグは公式ではCLIリファレンスと、セルフホスト環境のテストの手順ページに載っています。claude --helpをgrepして見つからなくても、フラグが無いわけではない点に注意が要ります。

ローカルのHEADとは別のブランチで検証したいとき

--environmentだけを渡すと、セッションは実行したディレクトリのローカルHEADをチェックアウトします。手元の作業ブランチと動かしたいブランチが違うなら、事前にgit checkoutで切り替えるか、--refで明示するかのどちらかです。

CIホストや自分の作業マシンをmainに置いたまま、リリース候補やPRのブランチへセッションをディスパッチしたい場面が典型です。ローカルの作業状態を動かさずに済みます。Environment・Runner・Sessionの3要素はClaude Code self-hosted-runnerとはで扱っています。

コマンドの書き方と実行後に起きること

--environmentにはセルフホスト環境のID(ccpool_で始まる)を渡し、--refにはブランチ名を渡します。

claude -p "smokeテストを実行して結果を返して" \
  --environment ccpool_abc123 \
  --ref release/2.4 \
  --output-format json

実行場所は、gitチェックアウトの中でなければなりません。Claude Codeがoriginリモートからリポジトリを自動検出するためで、チェックアウトの外やoriginの無いリポジトリでは検出できません。コマンドはセッションを作ると、session_idを含む1行のJSONを出力してすぐ終了します。--output-formatを付けない場合は、セッションIDとセッションへのリンクが出力されます。

--environmentに渡すIDは、claude.aiの管理画面「Cloud environments」でEnvironmentの詳細ダイアログを開くと表示されます。APIの応答フィールドやトークンのクレーム、メトリクス名ではこのEnvironmentがpoolという語で現れ、ccpool_というIDもその命名に由来します。呼び方が違うだけで、指しているものは同じです。

作成済みセッションへの追加メッセージは--refではなく、--cloud <session-id>で送ります。--refが効くのはセッションを新規作成する瞬間だけです。--environmentと--refはセッションを作る側(開発者やCI)のフラグで、自社ホストでRunnerを起動・登録するのはclaude self-hosted-runnerという別のコマンドです。

CIスクリプトでは変数に逃がす

セルフホスト環境のテストの手順ページにあるサンプルスクリプトは、--refの値をシェル変数に切り出して、既定をmainにしています。

: "${TEST_REPO_REF:=main}"
create_json=$(claude -p "$TURN1" --environment "$CLAUDE_TEST_ENVIRONMENT_ID" \
  --ref "$TEST_REPO_REF" --output-format json)

同じスクリプトには、CLAUDE_TEST_ENVIRONMENT_IDが空のとき旧名のCLAUDE_TEST_POOL_IDを読む1行もあります。poolとenvironmentの呼び名が混在していた名残で、古いスクリプトを引き継ぐ際は両方の名前に出会う可能性があります。

認証にはclaude.aiのOAuthトークンを使い、sk-ant-で始まるAPIキーは--environmentにも--cloudにも受け付けられません。長期稼働のCIホストでは、事前にclaude auth loginを済ませておきます。リフレッシュトークンは初回ログインから30日が上限なので、30日ごとに再ログインが要ります。1年有効なclaude setup-tokenのトークンは、セッションを操作する権限を含まないので使えません。使い捨てのCIランナーではCLAUDE_CODE_OAUTH_REFRESH_TOKENとCLAUDE_CODE_OAUTH_SCOPESで保存済みのログインを渡せますが、こちらにも同じ30日の上限があります。

一緒に指定できないフラグ

--environmentは新規セッションを作るためのフラグなので、既存セッションの再開や事前設定にあたるフラグとは組み合わせられません。--refも同じ制約を受けます。

動いているセッションのブランチを後から--refで差し替える手段はありません。変えたいときは新しいセッションを作り直します。Runner側のフラグ(--retire-atや--drain-grace-secなど)はClaude Codeセルフホスト環境のCLIフラグ・メトリクスリファレンスにまとめています。

ローカルの--worktreeはブランチ名を渡せない

「ブランチを指定してセッションを始める」点で紛らわしいのが、ローカルで動く--worktree(-w)です。claude --helpでは-w, --worktree [name]と表示され、nameは作成するworktreeの名前です。ブランチ名の指定ではありません。

--worktreeは#1234形式のPR番号や、GitHubのPR・GitLabのMRのURLを受け取れます。originからそのhead commitを取得して、その変更を起点にworktreeを作ります。それ以外の既存ブランチから始めたいときは、git worktree addで直接作る方法が公式に案内されています。--refが効くのはセルフホスト環境のセッションだけで、ローカルのclaude起動には影響しません。

--refが使える組織の条件

--refはセルフホスト環境のある組織でしか意味を持たないため、利用条件も押さえておく必要があります。

• プランと有効化: TeamとEnterpriseのパブリックベータで、既定では無効です。組織のOwnerが管理画面の「Cloud environments」で「Allow self-hosted environments」を有効にします。その前提として、組織でクラウドセッション(Claude Code on the web)が有効になっている必要があります
• Zero Data Retention: 有効にしている組織では使えません
• リポジトリ: セッションがチェックアウトするのはGitHubのリポジトリです。GitHub Enterprise Serverのホストを使う場合は、公式にネットワーク要件のページがあります
• 課金: セルフホスト環境のセッションも、Anthropicホスト環境と同じ形で組織のClaude Code利用枠を消費します
• 対応する起動経路: claude.ai/code、モバイル・デスクトップアプリ、スケジュール実行のroutines、ターミナルの--cloudまたは--environmentディスパッチが対象です。Claude Tagのセッションも動きますが、Access bundlesはまだ使えません。Claude SecurityとCode Reviewのセッションは、まだセルフホスト環境にルーティングされません

セルフホストを選ぶ動機は、社内ネットワークへのアクセス、独自ツールの事前インストール、コンプライアンス上の理由でセッションの実行場所を自社管理下に置くことです。「セルフホスト環境」と「self-hosted-runner」の指す範囲に迷うときは、self-hosted environmentsとself-hosted-runnerの違いが助けになります。

よくあるつまずき

どれも--ref単体の不具合ではなく、--environmentディスパッチ全体の制約が原因です。

• claude --helpに--refが出ない: v2.1.289の--helpには載っていませんが、v2.1.224以降のCLIで使えるフラグです。バージョンが古いと使えないので、claude --versionで確かめ、古ければclaude updateで更新します
• gitチェックアウトの外から実行した: リポジトリはoriginから自動検出されるので、チェックアウト外やoriginの無いリポジトリでは失敗します
• 走っているセッションのブランチを変えようとした: --refが効くのは新規作成時だけで、--resumeや--continueとの併用は不可です
• ローカルのブランチ切り替えと同じ感覚で使った: --refはセルフホスト環境上のチェックアウトにしか作用せず、ローカルの作業ツリーには触れません
• 認証が済んでいないホストから実行した: 非対話でセッションを作るには、そのマシンで事前にclaude auth loginが必要です

まとめ

ローカルのブランチを動かさずに共有Runner上で別ブランチを検証したいなら--ref、手元での並列作業なら--worktreeと、解く課題が別です。ブランチを変えたいときは、--resumeなどで延命せず新しいセッションを作り直す前提で運用します。