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

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

Deep Linksとは何か

Deep Linksは、mailto:リンクがメールクライアントを開くのと同じ要領で、OSに登録したカスタムURLスキームclaude-cli://からClaude Codeを起動する機能です。リンクの中に作業ディレクトリとプロンプトの下書きを埋め込めるため、クリックした人は「すでにプロンプトが入力された状態のセッション」を即座に受け取れます。

典型的な使いどころは次の4つです。

• 障害対応のランブックで、影響を受けたサービスのリポジトリを診断プロンプト付きで開くステップ
• 監視アラートやダッシュボードから、特定の指標を調査するプロンプトへのリンク
• READMEやWikiで、オンボーディング用プロンプトを添えてプロジェクトを開くリンク
• CI失敗通知から、失敗したジョブ名を埋め込んで即座に調査を始めるリンク

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

リンクをクリックしてからセッションが開くまでは、4つの段階を踏みます。

1. ブラウザーやアプリがURLをOSに渡す
2. OSがclaude-cli://の接頭辞を認識し、そのマシン上でClaude Codeを起動する
3. リンクが指定したディレクトリで新しいターミナルウィンドウが開き、入力欄にプロンプトがすでに入力された状態になる
4. 内容を読み、必要なら編集し、Enterを押して送信する

Deep Linkは自分では何も実行しません。リンクが選ぶのはディレクトリとプロンプトの中身だけです。信頼していないページ経由のリンクをクリックしても、プロンプトはEnterを押すまで無害なままです。

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

リンクを組み立てる

すべてのDeep Linkはclaude-cli://openから始まり、これ以外のパスはハンドラーが受け付けません。パラメータなしの最小形は、ホームディレクトリを空のプロンプトで開きます。

claude-cli://open

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

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.

cwdとrepo、どちらを使うべきか

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

配布シーンによって向き不向きが分かれます。

ランブックに埋め込む

ランブックに埋め込んだDeep Linkは、対応にあたる人へ「正しいリポジトリで、下書き済みのプロンプトから調査を始められるワンクリックの入口」を用意します。プロンプトは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://はクリックできるリンクになりません。カスタムURLスキームを許可していないため、ラベルだけが表示されリンクは失われます。GitHub上で使う場合は、コードブロックにURLをそのまま書き、読者が自分でブラウザーのアドレスバーに貼り付けられるようにします。

シェルから直接開く

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

open "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が起動していなければ先に起動し、すでに起動していればフォーカス中のウィンドウでタブが開きます。

2つのハンドラーは見た目が似ていますが、できることが違います。

claude-cli://側はセッションIDを受け取る仕組みそのものがなく、開くたびに新規セッションになります。ターミナルセッションを開きたいならclaude-cli://、VS Code内のタブとして開きたいならvscode://anthropic.claude-code/openです。エディタでの操作性を保ったまま調査を始めたいチームでは、後者のほうが自然に馴染みます。VS Code拡張の設定全般はClaude Code VS Code拡張の設定ガイドにまとめています。

登録の仕組みと無効化

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

どのターミナルが開くか

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

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

希望のターミナルで開かせたい場合、macOSではそのターミナルで一度claudeを起動しておけば次のDeep Linkから使われます。Linuxでは$TERMINALに希望のエミュレータのコマンド名を設定します。Windowsは優先順位が固定なので、Windows Terminalで開かせたいならインストールしておく必要があります。

よくあるつまずき

• リンクをクリックしても何も起きない: ハンドラーがまだ登録されていない可能性があります。登録はインタラクティブセッションの最初のプロンプトを送った時点で行われるため、そのマシンで一度claudeを起動しプロンプトを送ってから、リンクを開き直します
• Linuxでxdg-open: command not foundと出る: xdg-utilsパッケージが入っていません。最小構成のサーバーイメージ・コンテナ・WSLディストリビューションでは省かれていることが多く、sudo apt install xdg-utils等で導入します
• Linuxでxdg-utilsを入れてもリンクが開かない: xdg-openはデスクトップ環境が登録したURLハンドラーへ処理を渡すコマンドです。GUIのないサーバーやヘッドレスなコンテナにはそもそも渡す先が無いため、xdg-utilsを入れただけでは解決しません。デスクトップ環境のあるマシンでリンクを開きます
• GitHub上でリンクがただの文字列になる: GitHubのMarkdownレンダラーはhttp/https以外のURLスキームを許可しないため、claude-cli://はラベルだけが残りリンクが失われます。コードブロックでURLをそのまま見せる形に切り替えます
• repoで開いたのにホームディレクトリで開く: repoパラメータは、Claude Codeが過去に見たことのあるクローンにしか解決できません。対象のクローン内で一度claudeを実行してパスを記録させるか、cwdに絶対パスを指定する形へ切り替えます

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

Deep Links関連の挙動は複数のバージョンにまたがって変わってきました。今の挙動だけを見ていると、なぜそう動くのか分かりにくい部分があるため、版番号付きでまとめておきます。

これらは個別の修正として見るとバラバラですが、並べると「登録・起動・警告表示」という3つの弱点を順番に潰してきた流れが見えます。

よくある質問

信頼していないサイトに置かれたDeep Linkをクリックしても安全ですか

リンク自体はディレクトリとプロンプトの下書きを選ぶだけで、何も実行しません。開いたセッションでプロンプトの内容を確認し、必要なら編集してからEnterを押すまでは何も送信されません。長いプロンプトでは文字数付きの警告が出るので、画面外に隠れた指示がないか確認してから送信してください。

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

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

ターミナルを開かずに調査を自動化したい場合はどうしますか

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

ブランチを指定してリポジトリを開けますか

できません。repoやcwdはディレクトリを選ぶだけで、そのディレクトリが現在チェックアウトしている状態のままセッションが開きます。特定のブランチやワークツリーを使いたい場合は、あらかじめそのディレクトリでclaudeを実行してパスを記録させておく必要があります。

まとめ

Deep Linksはclaude-cli://openにディレクトリとプロンプトをURLエンコードして渡すだけの仕組みで、ランブックやアラートに埋め込んで調査の入口を一元化できます。クリックした瞬間に何かが実行されることはなく、Enterを押すまでは常に確認できる状態です。

VS Code内で完結させたいセッションにはvscode://anthropic.claude-code/open、組織としてハンドラー登録自体を止めたい場合はmanaged settings経由のdisableDeepLinkRegistrationを使います。どちらもDeep Linksと同じ設定レイヤーに属する隣接機能なので、導入時にあわせて確認しておく価値があります。