Claude Media
Claude Code Deep Links — URLから直接セッションを起動する
Claude Codeチュートリアル

Claude Code Deep Links — URLから直接セッションを起動する

claude-cli://で始まるDeep Linksの仕組みと、ランブックやアラートに埋め込んでワンクリックでセッションを開く手順をまとめます。

読了目安 約16分

Deep Linksは、claude-cli://から始まるURLをクリックするだけでClaude Codeの新しいターミナルセッションを開ける仕組みです。作業ディレクトリとプロンプトの下書きをURLに乗せられるため、インシデントのランブック・監視アラート・ダッシュボードに埋め込んで、調査の出発点をワンクリックで用意する用途に向きます。プロンプトは自動送信されず、Enterを押すまで何も実行されません。クラウドセッション側の入口はclaude.ai/codeのURLパラメータで事前入力できます。

Deep Linksとは何か

Deep Linksは、mailto:リンクがメールクライアントを開くのと同じ要領で、OSに登録したカスタムURLスキームclaude-cli://からClaude Codeを起動する機能です。クリックした人は「すでにプロンプトが入力された状態のセッション」を受け取ります。リンク自体はどこに置いてもよく、セッションは常にクリックしたマシンのローカルで開きます。

使いどころ

リンクの置き場所の例

  • 障害対応のランブック

    影響を受けたサービスのリポジトリを、診断プロンプト付きで開くステップになります。

  • 監視アラート・ダッシュボード

    特定の指標を調べるプロンプトへのリンクを、グラフの横に置けます。

  • READMEやWiki

    オンボーディング用のプロンプトを添えて、プロジェクトを開くリンクです。

  • CI失敗の通知

    失敗したジョブ名をプロンプトに埋め込み、すぐ調査を始められます。

動作の仕組み — クリックからセッション起動まで

手順

クリックからEnterまで

  1. 1

    URLがOSに渡る

    ブラウザーやアプリが、クリックされたURLをOSに渡します。

  2. 2

    Claude Codeが起動する

    OSがclaude-cli://の接頭辞を認識し、そのマシン上でClaude Codeを起動します。

  3. 3

    下書き入りのターミナルが開く

    リンクが指定したディレクトリで新しいターミナルウィンドウが開き、入力欄にプロンプトが入った状態になります。

  4. 4

    読んで、直して、Enterで送る

    送信するまで、モデルには何も届きません。

Deep Linkは自分では何も実行しません。リンクが選ぶのはディレクトリとプロンプトの中身だけです。信頼していないページに貼られたリンクでも、この点は変わりません。

セッションが開くと、入力欄の下に原文でPrompt from an external link(外部リンクからのプロンプト)という警告行が表示され、送信するか消すまで残り続けます。プロンプトが1,000文字を超えると、警告に文字数が添えられます。画面外に隠れた指示がないか、スクロールして確認するよう促す文面です。選んだディレクトリに対する権限ルール・CLAUDE.md・信頼確認プロンプトは、通常のセッションと同じように適用されます。

リンクを組み立てる

すべてのDeep Linkはclaude-cli://openから始まります。パラメータなしの最小形は、ホームディレクトリを空のプロンプトで開きます。

claude-cli://open

作業ディレクトリとプロンプトの中身は、次のパラメータで指定します。

パラメータ説明
q説明プロンプト欄に入れるテキスト。URLエンコードが必要で、改行は%0A。最大5,000文字
cwd説明作業ディレクトリの絶対パス。ネットワークパスやUNCパス、..を含むパス、不可視・双方向制御文字を含むパスは拒否される
repo説明GitHubのowner/name形式のスラッグ。Claude Codeが過去に見たことのあるローカルクローンへ解決する。該当するクローンがなければホームディレクトリで開く

リンクを試すだけなら、ページに置かずにブラウザーのアドレスバーへ貼り付けても開けます。

cwdとrepoは両方とも作業ディレクトリを決める手段です。両方指定するとcwdが優先され、そのパスが存在しなくてもrepoは無視されます。

次のリンクはacme/paymentsリポジトリを、2行の診断プロンプト付きで開きます。

claude-cli://open?repo=acme/payments&q=Investigate%20the%20failed%20deploy%20of%20payments-api.%0ACheck%20recent%20commits%20to%20main%20and%20the%20last%20successful%20build.

日本語のプロンプトは何倍に膨らむか

qの値はURLエンコードを通すので、日本語は1文字が%E5%8E%9Fのような9文字に化けます。Node.jsでencodeURIComponent("原因を調べて。\nログも見て")を実行すると、次の出力になります。

claude-cli://open?q=%E5%8E%9F%E5%9B%A0%E3%82%92%E8%AA%BF%E3%81%B9%E3%81%A6%E3%80%82%0A%E3%83%AD%E3%82%B0%E3%82%82%E8%A6%8B%E3%81%A6

12文字の日本語に改行1つが、URLでは100文字を超えます。英数字と.は元のまま残り、スペースは%20、カンマは%2C、改行は%0Aに変わります。日本語のランブックでは、リンクが長くなる前提で設計します。

エンコード済みのリンクは、手でエンコードせずスクリプトで作るほうが確実です。たとえばacme/web-gateway向けのリンクは、次のコードで組み上がります。

node -e '
const q = "5xx rate is elevated on web-gateway.\nCheck recent deploys, error logs from the last 30 minutes.";
console.log("claude-cli://open?repo=acme/web-gateway&q=" + encodeURIComponent(q));
'

出力は次のとおりです(Node.jsで実行した結果)。

claude-cli://open?repo=acme/web-gateway&q=5xx%20rate%20is%20elevated%20on%20web-gateway.%0ACheck%20recent%20deploys%2C%20error%20logs%20from%20the%20last%2030%20minutes.

cwdとrepo、どちらを使うか

くらべる

パスの決め方

絶対パスで固定

cwd

全員が同じ絶対パスにプロジェクトを置いているときの指定です。

スラッグで解決

repo

クローン先が人によって違うときの指定です。スラッグを、各自のマシンで記録済みのパスへ解決します。

repoは、そのリポジトリのクローンやワークツリーの中で直近にclaudeを実行したディレクトリへ解決されます。claudeを実行するたびに、Claude Codeがそのパスをスラッグに紐づけて記録する仕組みです。クローンとワークツリーは別々に追跡されます。ブランチの切り替えはリンクの役目ではなく、開いた時点のディレクトリの状態のままセッションが始まります。どのパスに解決されたかは、ウェルカムヘッダーで確認できます。

配布の相手によって、向き不向きが分かれます。

配布シーン向くパラメータ理由
対象リポジトリでclaudeを一度も実行していない相手向くパラメータどちらも不向き理由repoは解決できずホームディレクトリで開き、cwdは相手のパスを事前に知る必要がある
devcontainerやVMイメージなど、全員が同じ絶対パスに置いている環境向くパラメータcwd理由解決の不確実性がない

ランブックに埋め込む

ランブックに埋め込んだDeep Linkは、対応にあたる人へ「正しいリポジトリで、下書き済みのプロンプトから調査を始められる入口」を用意します。プロンプトはURLエンコードが必須なので、ブラウザーのコンソールやURLエンコーダーでencodeURIComponentを通してから貼り付けます。

## web-gatewayの5xx率上昇
 
1. PagerDutyでページをAcknowledgeする
2. [gatewayリポジトリでClaude Codeを開く](claude-cli://open?repo=acme/web-gateway&q=5xx%20rate%20is%20elevated...)
3. #incidentに初期の調査結果を投稿する

GitHubが描画するMarkdown(README・Issue・プルリクエスト・Wiki)では、claude-cli://はクリックできるリンクになりません。httpとhttps以外のスキームが除去され、[ラベル](claude-cli://...)はラベルだけが残ります。GitHub上で使う場合は、コードブロックにURLをそのまま書き、読者が自分でブラウザーのアドレスバーに貼り付けられるようにします。

シェルから直接開く

リンクをクリックする代わりに、シェルスクリプトやエイリアスからOSのURLオープンコマンドを呼び出すこともできます。いずれも、マシン上でインタラクティブセッションの最初のプロンプトを送った時にClaude Codeが登録したハンドラーに依存します。

OSコマンド
macOSコマンドopen "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"
Linuxコマンドxdg-open "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"
Windows(PowerShell)コマンドStart-Process "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"

cmd.exeではstartが最初の引用符付き引数をウィンドウタイトルとして扱うため、空のタイトルをURLの前に渡します(start "" "claude-cli://...")。

VS Codeタブを開く場合との使い分け

VS Code拡張機能は、claude-cli://とは別にvscode://anthropic.claude-code/openという独自のハンドラーを登録しています。こちらはターミナルではなく、VS Code内のClaude Codeタブを開きます。VS Codeが起動していなければ先に起動し、すでに起動していればフォーカス中のウィンドウでタブが開きます。

比較項目claude-cli://openvscode://anthropic.claude-code/open
開く先claude-cli://open新しいターミナルウィンドウvscode://anthropic.claude-code/openVS Code内のClaude Codeタブ
パス指定手段claude-cli://opencwd(絶対パス)/ repo(スラッグ)vscode://anthropic.claude-code/open開いているワークスペースに固定(パス指定なし)
プロンプト用パラメータ名claude-cli://openqvscode://anthropic.claude-code/openprompt
セッション再開claude-cli://open不可(常に新規セッション)vscode://anthropic.claude-code/opensessionパラメータで再開可(該当ワークスペースのセッションでなければ新規会話になる)
ハンドラーの登録claude-cli://openインタラクティブセッションの最初のプロンプト送信時vscode://anthropic.claude-code/open拡張機能が登録

vscode://側のURLはvscode://anthropic.claude-code/open?prompt=review%20my%20changesの形で、パラメータ名がqでなくpromptになる点が最初の落とし穴です。sessionには、すでにタブで開いているセッションIDを渡すと、そのタブにフォーカスが移ります。ターミナルセッションを開きたいならclaude-cli://、VS Code内のタブとして開きたいならvscode://anthropic.claude-code/openです。VS Code拡張の設定全般はClaude Code VS Code拡張の設定ガイドにまとめています。プラグインの導入画面へ直接案内するinstall-pluginリンクはプラグイン導入リンクの作り方で扱っています。

登録の仕組みと無効化

claude-cli://ハンドラーは、macOS・Linux・Windowsのいずれでも、インタラクティブセッションの最初のプロンプトを送った時に登録されます。claudeを起動してプロンプトを送らずに終了しただけでは登録されません。別途インストールコマンドは不要で、ユーザーレベルの場所にだけ書き込まれます。

OS登録先
macOS登録先~/Applications/Claude Code URL Handler.app
Linux登録先$XDG_DATA_HOME/applications下のclaude-code-url-handler.desktop(既定は~/.local/share/applications)
Windows登録先HKEY_CURRENT_USER\Software\Classes\claude-cli

どのターミナルが開くか

Deep Linkが開くターミナルエミュレータは、OSごとに選び方が違います。

  • macOS: 直近のインタラクティブセッションで使ったターミナルを記憶して再利用します。iTerm2・Ghostty・kitty・Alacritty・WezTerm・Terminal.appに対応しています
  • Linux: $TERMINAL環境変数を優先し、次にx-terminal-emulator、それでも見つからなければ主要なエミュレータの一覧から選びます
  • Windows: Windows Terminalを優先し、次にPowerShell、最後にcmd.exeの順で選びます

症状別のつまずき

  • リンクをクリックしても何も起きない: ハンドラーがまだ登録されていない可能性があります。登録を済ませてからリンクを開き直します。GUIのないLinuxでは、xdg-openが渡す先を持たないことも原因になります
  • Linuxでxdg-open: command not foundと出る: xdg-utilsパッケージが入っていません。最小構成のサーバーイメージ・コンテナ・WSLディストリビューションでは省かれていることがあり、sudo apt install xdg-utils等で導入します
  • xdg-utilsを入れてもリンクが開かない: xdg-openはデスクトップ環境が登録したURLハンドラーへ処理を渡すコマンドです。デスクトップ環境のあるマシンでリンクを開きます
  • repoで開いたのにホームディレクトリで開く: repoは、Claude Codeが過去に見たことのあるクローンにしか解決できません。対象のクローン内で一度claudeを実行してパスを記録させるか、cwdに絶対パスを指定します
  • 意図しないターミナルで開く: macOSでは希望のターミナルで一度claudeを起動しておけば、次のDeep Linkから使われます。Linuxでは$TERMINALに希望のエミュレータのコマンド名を設定します。Windowsは優先順位が固定なので、Windows Terminalで開かせたいならインストールしておきます

バージョンごとの変更履歴

Deep Links関連の挙動は、複数のバージョンにまたがって変わってきました。

あゆみ

Deep Linksの変更履歴

  1. v2.1.83登録の停止設定とXDG対応

    disableDeepLinkRegistrationが追加され、Linuxの登録先がXDG_DATA_HOME基準になりました。

  2. v2.1.84ターミナルの記憶

    優先するターミナルを記憶し、次回以降そのターミナルで開くようになりました。

  3. v2.1.855,000文字まで拡張

    qが5,000文字まで使えるようになり、長いプロンプトにはスクロール確認を促す警告が付きました。

  4. v2.1.89macOSで開かない不具合を修正

    macOSでリンクをクリックしても開かない不具合が直りました。

  5. v2.1.91複数行プロンプト

    %0Aによる改行が拒否されなくなり、複数行プロンプトを送れるようになりました。

  6. v2.1.162警告行の固定表示

    起動時の警告が、操作するまで入力欄の下に固定されるようになりました。

よくある質問

長いランブックのプロンプトを毎回URLに埋め込むのは大変です

繰り返し使うプロンプトは、リポジトリにSkillsとして保存し、Deep Linkのqパラメータではスキル名だけを指定する形にすると、URLを短く保てます。

ターミナルを開かずに調査の結果だけ受け取りたい場合はどうしますか

Deep Linksは人がクリックしてターミナルを開く前提の機能です。スクリプトから出力を受け取って処理したい場合は、非対話モード(-p)のほうが向きます。

まとめ

配布の前に確かめておくのは、相手が対象リポジトリで一度でもclaudeを実行しているか、という点です。実行済みならrepoで足り、そうでなければcwdの絶対パスを揃えるか、リンクの前に手順で一度起動してもらう形になります。

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

関連する記事

Claude Code をもっと見る →