Claude Media
CLAUDE_CODE_BRIDGE_SESSION_IDでRemote Control接続元を特定する
Claude CodeTips

CLAUDE_CODE_BRIDGE_SESSION_IDでRemote Control接続元を特定する

Bash/hookサブプロセスに自動セットされる環境変数から、Remote Control経由のセッションをスクリプトで特定する方法をまとめます。

読了目安 約11分

このTipsでできること

Remote Control接続中のセッションでBashコマンドやhookを実行すると、そのサブプロセスにCLAUDE_CODE_BRIDGE_SESSION_IDという環境変数が自動的にセットされます。この変数を読み取れば、スクリプト側から「いまどのセッションで実行されているか」をリンク付きで特定できます。ローカル実行とRemote Control実行を区別する通知スクリプトや、実行結果にセッションへの戻りリンクを添えるSessionEnd hookを書くときに使います。

CLAUDE_CODE_BRIDGE_SESSION_IDとは何か

CLAUDE_CODE_BRIDGE_SESSION_IDは、セッションがRemote Control接続を持っている間だけ、BashツールとHookコマンドのサブプロセスにセットされます。接続が切れると変数は削除されます。値はセッションのclaude.ai/codeURLに現れるものと同じsession_形式のIDで、スクリプトから実行元のセッションへリンクを組み立てられます。この変数はClaude Code v2.1.199以降が対象です。

やり方 — Bash/hookからセッションURLを組み立てる

もっとも単純な使い方は、Bashツールで実行するスクリプトの中で変数の有無を見て分岐することです。

if [ -n "$CLAUDE_CODE_BRIDGE_SESSION_ID" ]; then
  echo "Remote Control経由: https://claude.ai/code/${CLAUDE_CODE_BRIDGE_SESSION_ID}"
else
  echo "ローカル実行"
fi

hookコマンドから使う場合も同じ変数を読むだけです。たとえばテストの失敗を外部に通知するhookで、失敗が起きたセッションへのリンクを本文に含められます。

#!/bin/bash
SESSION_URL=""
if [ -n "$CLAUDE_CODE_BRIDGE_SESSION_ID" ]; then
  SESSION_URL="https://claude.ai/code/${CLAUDE_CODE_BRIDGE_SESSION_ID}"
fi
curl -s -X POST "$WEBHOOK_URL" \
  -d "{\"text\": \"テストが失敗しました ${SESSION_URL}\"}"

このhookをhooks設定に登録すれば、Remote Controlでスマホから走らせているセッションでテストが落ちたときだけ、通知にセッションへの戻りリンクが付きます。ローカルのターミナルから直接実行している間はCLAUDE_CODE_BRIDGE_SESSION_IDが未設定なので、SESSION_URLは空文字のままになり、通知本文からリンクが自然に消えます。

hookの登録自体は他のhookと変わりません。上のスクリプトをnotify-on-fail.shとして保存し、プロジェクトの.claude/settings.jsonにexec形式で登録する例です。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/notify-on-fail.sh"
          }
        ]
      }
    ]
  }
}

${CLAUDE_PROJECT_DIR}はセッション開始時のプロジェクトルートを指す別の環境変数で、hookスクリプトの置き場所を絶対パスに固定するために使います。CLAUDE_CODE_BRIDGE_SESSION_IDとは役割が異なり、こちらはRemote Controlの有無に関係なく常にセットされます。

クラウドセッションとの使い分け早見表

同じ「セッションを特定したい」という目的でも、実行場所によって読むべき環境変数が変わります。

実行環境セットされる変数値の形式
ローカルCLI(Remote Control未接続)セットされる変数どちらも未設定値の形式—
ローカルCLI + Remote Control接続中セットされる変数CLAUDE_CODE_BRIDGE_SESSION_ID(Bash/hookサブプロセスのみ)値の形式session_形式
クラウドセッション(claude.ai/code上で実行)セットされる変数CLAUDE_CODE_REMOTE_SESSION_ID値の形式現在のセッションID
クラウドセッションかどうかの判定セットされる変数CLAUDE_CODE_REMOTEが"true"値の形式真偽値文字列

CLAUDE_CODE_REMOTE_SESSION_IDはクラウドセッション自身が読み取り、実行結果からセッションのトランスクリプトへのリンクを組み立てるための変数です。一方CLAUDE_CODE_BRIDGE_SESSION_IDは、ローカルマシンで動くセッションがRemote Controlで橋渡しされているときに限って現れます。スクリプトを両方の環境で共用するなら、CLAUDE_CODE_REMOTEで先にクラウドかどうかを判定し、クラウドでなければCLAUDE_CODE_BRIDGE_SESSION_IDの有無を見る、という順序が素直です。複数のセッションを並行して動かしていて名前や見た目で区別したい場合は、Claude Codeでセッションを見分ける方法も合わせて参照してください。

Remote Control自体が使えないと変数も現れない

CLAUDE_CODE_BRIDGE_SESSION_IDはRemote Controlの接続を前提にした変数なので、Remote Controlが無効な構成では最初から値が入りません。公式のRequirements節が挙げる主な条件は次のとおりです。

  • Amazon Bedrock、Google CloudのAgent Platform、Microsoft Foundryのいずれかを使っている
  • ANTHROPIC_BASE_URLをapi.anthropic.com以外のホスト(LLMゲートウェイやプロキシ)に向けている
  • 企業向けのClaude apps gatewayでサインインしている
  • CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICまたはDISABLE_GROWTHBOOKを設定し、フィーチャーフラグの取得自体を止めている
  • プロジェクトディレクトリでまだ一度もclaudeを実行しておらず、起動時のワークスペース信頼ダイアログを承認していない(ホームディレクトリでは信頼が保存されないため、必ずプロジェクトディレクトリから起動する)

これらに該当する環境で「スクリプトがセッションを検知できない」と感じたら、変数名の綴りより先にRemote Controlそのものが有効かを疑うのが近道です。管理者がClaude Code admin settingsでRemote Controlのトグルを無効化しているTeam・Enterpriseプランでも同様に変数はセットされません。接続自体がそもそも確立できない、あるいは頻繁に切れる場合の切り分けはRemote Controlに接続できないときの見分け方と対処を参照してください。

環境変数の継承に関する注意点

hookプロセスは基本的に親プロセスの環境変数をそのまま引き継ぎますが、無条件ではありません。CLAUDE_CODE_SUBPROCESS_ENV_SCRUBを1にすると、Bashツール・hook・MCP stdioサーバーのサブプロセスからAnthropicやクラウドプロバイダーの資格情報、レジストリURLに埋め込まれた資格情報など、Claude Codeが資格情報と認識する変数が取り除かれます。v2.1.251以降はCLAUDE_CONFIG_DIRのような設定ストアの参照変数も除去対象に加わります。CLAUDE_CODE_BRIDGE_SESSION_IDはこの除去対象として挙がっていないので、SCRUBを有効にしている環境でも読み取りには影響しません。

HTTP形式のhookでヘッダーに環境変数を載せる場合は事情が変わります。headersフィールドの値は$VAR_NAMEや${VAR_NAME}の形式で変数を参照できますが、allowedEnvVarsに列挙した変数だけが実際に解決され、一覧にない変数への参照は空文字に置き換わります。CLAUDE_CODE_BRIDGE_SESSION_IDをWebhookヘッダーに含めたいときは、allowedEnvVarsへの追記を忘れると常に空のヘッダーが送られる点に注意してください。

よくある質問

CLAUDE_CODE_BRIDGE_SESSION_IDの値は外部に送っても問題ないか

値自体はセッションを指す識別子で、パスワードやAPIキーのような認証情報ではありません。とはいえ値からセッションのURLをそのまま組み立てられるため、社内向けの通知チャネルなど、送信先は限定しておくのが無難です。

Bashツール以外(ステータスラインなど)でも同じ変数を読めるか

公式docsが明記しているのはBashツールとhookコマンドのサブプロセスです。ステータスラインスクリプトなど、別の仕組みで起動されるプロセスに同じ変数が渡るかどうかは、この2つと同列には保証されていません。用途が異なる箇所で使う場合は、まずecho $CLAUDE_CODE_BRIDGE_SESSION_IDで実際に値が入るかを確認してから組み込みます。

v2.1.199より前のバージョンでは代わりに何を使うか

CLAUDE_CODE_BRIDGE_SESSION_ID自体がv2.1.199で追加された変数なので、それより前のバージョンに直接の代替手段はありません。まずclaude --versionで手元のバージョンを確認し、古い場合はアップデートしてから組み込みます。なおv2.1.79で先に導入されたのはVSCode拡張の/remote-controlで、CLI(ターミナル)のRemote Controlとは別の導入時期です。

よくあるつまずき

  • 接続が切れた瞬間に変数も消える: CLAUDE_CODE_BRIDGE_SESSION_IDは接続が有効な間だけ存在するため、hookの中で一度読み取った値をキャッシュせず、サブプロセスのたびに読み直す前提でスクリプトを書きます。放置による自動切断のタイミングはRemote Controlが20分放置で切断される原因と回避策にまとめています
  • Remote Controlサーバーの--spawn worktreeと組み合わせるとき: サーバーを--spawn worktreeで起動すると、オンデマンドで作られるセッションごとに別のgit worktreeが割り当てられます。CLAUDE_CODE_BRIDGE_SESSION_IDはあくまでセッションを指す識別子で、worktreeのパスは分かりません。作業中のworktreeのパスが必要なときは、Claudeの作業ディレクトリに追従するhook入力JSONのcwdフィールドを読みます
  • セットされるのはBash/hookサブプロセスだけ: CLAUDE_CODE_BRIDGE_SESSION_IDはBashツールとhookコマンドのサブプロセスに限って渡される変数です。それ以外の経路で環境変数を確認しようとしても、同じ場所に値は現れません

まとめ

CLAUDE_CODE_BRIDGE_SESSION_IDは、Remote Control接続中のセッションでBash・hookサブプロセスからセッションを特定したいときに読む環境変数です。クラウドセッションではCLAUDE_CODE_REMOTE_SESSION_IDを読むという使い分けさえ間違えなければ、通知スクリプトやhookに「どのセッションからの結果か」を1行足すだけで組み込めます。Remote Control自体を使っていない、またはBedrock・独自ゲートウェイ経由などRemote Controlの利用条件を満たしていない環境では変数が現れない点だけ覚えておくと、原因調査で遠回りせずに済みます。

導入自体は既存のスクリプトに数行のif分岐を足すだけで完結するため、複数人でRemote Controlを併用しているチームほど、hookの通知に戻りリンクを仕込んでおく価値は大きくなります。

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

関連する記事

Claude Code をもっと見る →