Claude Code のディープリンク: claude-cli:// でセッションを開く

障害対応の手順書に「このリポジトリで、この調査プロンプトから始める」というリンクを1つ置いておけたら、対応の立ち上がりが速くなります。Claude Code のディープリンクは claude-cli:// で始まる URL で、クリックすると新しいターミナルウィンドウで Claude Code が開き、指定した作業ディレクトリでプロンプトが入力済みの状態になります。プロンプトは Enter を押すまで送信されません。

本記事は公式ドキュメント「Launch sessions from links」に基づき、リンクの書き方・使いどころ・ハンドラーの登録と無効化・うまく動かないときの対処を日本語で解説します。公式が挙げる使いどころは次のとおりです。

インシデント対応のランブックの1手順として、影響を受けたサービスのリポジトリを診断プロンプト付きで開く
監視アラートやダッシュボードから、特定のメトリクスを調べるプロンプトへリンクする
README や社内 Wiki から、オンボーディング用プロンプト付きでプロジェクトを開く
CI の失敗通知に、失敗したジョブ名を入れたプロンプトを添える

ディープリンクの仕組みと安全性

claude-cli:// は Claude Code が OS に登録するカスタム URL スキームです。mailto: のリンクでメールソフトが開くのと同じ仕組みで、リンクをクリックすると次の順に処理されます。

ブラウザやアプリが URL を OS に渡す
OS が claude-cli:// を認識し、そのマシンで Claude Code を起動する
新しいターミナルウィンドウが開き、リンクで指定したディレクトリで Claude Code が動き、入力欄にリンクのプロンプトが入っている
利用者がプロンプトを読み、必要なら編集して Enter で送信する

リンク自体はどこに置いてもかまいませんが、セッションは常にクリックした人のコンピューター上でローカルに開きます。また、リンクを表示する側のプラットフォームがカスタム URL スキームを許可している必要があります（GitHub は許可していません。後述）。

リンクを開いただけでは何も実行されない

ディープリンクが行うのは「ディレクトリを選ぶ」「入力欄を埋める」の2つだけです。信頼できないページのリンクをクリックしても、入力された内容を読んで Enter を押すまで、何もモデルには届きません。

リンクから開いたセッションでは、入力欄の下に Prompt from an external link という警告行が表示され、プロンプトを送信するか消去するまで残ります。プロンプトが 1,000 文字を超える場合は、警告に文字数が含まれ、Enter を押す前にスクロールして全文を確認するよう促されます。長いプロンプトでは指示が画面外に押し出されることがあるためです。権限ルール、CLAUDE.md、選んだディレクトリの信頼確認（trust prompt）は、通常のセッションと同じように適用されます。

リンクの作り方（q・cwd・repo）

ディープリンクは claude-cli://open で始まり、必要に応じてクエリパラメーターを付けます。最小の形は次のとおりで、ホームディレクトリで空のプロンプトのまま Claude Code が開きます。

claude-cli://open

ページに置く前に試したい場合は、ブラウザのアドレスバーに貼り付けるか、後述のシェルコマンドで開きます。使えるパラメーターは3つです。

パラメーター	内容
`q`	入力欄にあらかじめ入れるテキスト。URL エンコードが必要で、複数行にするときは改行を `%0A` で表す。最大 5,000 文字
`cwd`	作業ディレクトリにする絶対パス。ネットワークパスや UNC パス、`..` を含むパス、不可視文字や双方向制御文字を含むパスは拒否される
`repo`	GitHub の `owner/name` 形式のスラッグ。Claude Code が以前に見たローカルのクローンに解決してそこで開く。該当するクローンが無ければホームディレクトリで開く

cwd と repo を両方指定すると cwd が優先され、cwd のパスが存在しない場合でも repo は無視されます。

公式の例では、acme/payments リポジトリを2行の診断プロンプト付きで開くリンクを次のように書いています（acme/payments は自分のリポジトリのスラッグに置き換えます）。

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

クリックすると、ローカルの acme/payments のクローンで Claude Code が起動し、入力欄にはデコードされた2行（「payments-api のデプロイ失敗を調べる」「main への最近のコミットと最後に成功したビルドを確認する」という指示）が入ります。送信前に編集もできます。

プロンプトは URL の一部なので、日本語を含めてエンコードが必要です。ブラウザのコンソールで encodeURIComponent("...") を通すなど、任意の URL エンコーダーで変換した値を q に入れます。

cwd と repo の使い分け

cwd: リンクを開く全員が同じ絶対パスにプロジェクトを置いている場合（標準化された devcontainer や VM イメージなど）に使う
repo: リンクを共有し、各自が別々の場所にクローンしている場合に使う

repo は、そのリポジトリのクローンまたはワークツリーのうち、最後に claude を実行した場所で開きます。Git リポジトリ内で claude を実行するたびに、Claude Code はそのディレクトリのパスを GitHub の owner/name と結び付けて記録しており、クローンとワークツリーは別々に追跡されます。リンクはチェックアウト中のブランチを変えず、そのディレクトリの現在の状態のまま開きます。どのパスが選ばれたかはウェルカムヘッダーに表示されるので、意図したクローンかを確認できます。

ランブックへの埋め込みとシェルからの起動

ランブックに埋め込む

ランブックにディープリンクを置くと、トリアージ担当者が正しいリポジトリで、用意したプロンプトからワンクリックで調査を始められます。公式の例では、web-gateway というサービスの 5xx 増加時の手順の2番目に、次のような Markdown リンクを置いています。

## High 5xx rate on web-gateway

1. Acknowledge the page in PagerDuty.
2. [Open Claude Code in the gateway repo](claude-cli://open?repo=acme/web-gateway&q=5xx%20rate%20is%20elevated%20on%20web-gateway.%20Check%20recent%20deploys%2C%20error%20logs%20from%20the%20last%2030%20minutes%2C%20and%20open%20incidents%20in%20Linear.)
3. Post initial findings in #incident.

Claude Code をインストール済みで、そのリポジトリのローカルクローンを持つエンジニアなら、手順2をクリックするだけで、送信待ちのプロンプトが入った状態から調査を始められます。ただし、GitHub でレンダリングされる Markdown は claude-cli:// を許可しないため、GitHub の README・Issue・Wiki ではラベルだけが表示され、クリックできません（対処は後述）。

ランブック用の長いプロンプトは、リポジトリにスキルとして保存しておけば、リンクの q ではそのスキル名を指定するだけで済む、と公式は案内しています。

シェルから開く

クリックの代わりに、シェルスクリプトやエイリアス、自動化から開くこともできます。OS の「URL を開く」コマンドにリンクを渡します。

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"`
Windows（cmd.exe）	`start "" "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"`

cmd.exe の start は最初の引用符付き引数をウィンドウタイトルとして扱うため、URL の前に空のタイトル "" を渡します。いずれも、後述のハンドラーがそのマシンに登録済みであることが前提です。なお、結果をスクリプトで受け取りたいだけならターミナルを開く必要はなく、非対話モード（claude -p）を使います。

ハンドラーの登録と無効化

Claude Code は、macOS・Linux・Windows で対話セッションの最初のプロンプトを送信したときに claude-cli:// のハンドラーを OS に登録します。別途インストールコマンドを打つ必要はありません。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`

どのターミナルで開くか

macOS: 直近の対話セッションで使ったターミナルを記憶して再利用する。対応は iTerm2・Ghostty・kitty・Alacritty・WezTerm・Terminal.app
Linux: 環境変数 $TERMINAL、次に x-terminal-emulator、次に一般的なエミュレーターの一覧の順に探す
Windows: Windows Terminal、次に PowerShell、次に cmd.exe の順

登録させない

ハンドラーを登録させたくない場合は、settings.json の disableDeepLinkRegistration で止めます。組織全体で強制し、利用者が戻せないようにするには、管理設定（managed settings）側で設定します。値の書き方は公式内で表記が分かれており、ディープリンクのページでは "disable" を指定する例、設定リファレンス（All settings）では真偽値の項目として記載されています。利用中のバージョンの設定リファレンスで確認してから設定してください。設定ファイルの置き場所と優先順位は設定と権限の記事にまとめています。

VS Code のタブで開きたい場合

VS Code 拡張機能は別のハンドラー vscode://anthropic.claude-code/open を登録しており、こちらはターミナルではなく VS Code のエディタータブで Claude Code を開きます。パラメーターは VS Code 向けドキュメントの「Launch a VS Code tab from other tools」に記載されています（IDE での使い方はIDE 連携の記事を参照）。

うまく開かないときの対処

症状	原因と対処
クリックしても何も起きない	ハンドラーが未登録の可能性。登録はセッション開始時ではなく最初のプロンプト送信時なので、そのマシンで対話セッションの `claude` を起動し、何かプロンプトを送ってから終了し、もう一度試す。デスクトップ環境の無い Linux では `xdg-open` に渡す先が無いことがある
Linux で `xdg-open` が見つからない	`xdg-open` は `xdg-utils` パッケージに含まれ、最小構成のサーバーイメージ・コンテナ・WSL では入っていないことが多い。`sudo apt install xdg-utils` などで入れて再実行する
リンクがただの文字列になりクリックできない	Markdown レンダラーによっては `http`/`https` 以外のスキームを除去する。GitHub の README・Issue・PR・Wiki では `[label](claude-cli://...)` が `label` だけになる。こうした場所ではリンクをコードブロックに入れ、読者がコピーしてブラウザのアドレスバーに貼れるようにする
リポジトリではなくホームディレクトリで開く	`repo` は Claude Code が見たことのあるクローンにしか解決しない。そのクローン内で一度 `claude` を実行してパスを記録させるか、`cwd` に絶対パスを指定する形に切り替える
意図しないターミナルで開く	macOS は使いたいターミナルで一度 `claude` を起動すれば次からそれが使われる。Linux は `$TERMINAL` に使いたいエミュレーターのコマンド名を設定する。Windows は順序が固定なので、Windows Terminal で開きたい場合はインストールする

ターミナル側の設定についてはターミナル設定の記事も参考になります。

本記事は Anthropic 公式ドキュメント「Launch sessions from links」に基づく非公式の日本語解説です（確認日 2026-10-01）。日本語版ドキュメントと設定リファレンス（All settings）の disableDeepLinkRegistration の項とも照合しています。仕様は更新される場合があるため、利用前に公式ドキュメントをご確認ください。