Skip to main content
A deep link is a claude-cli:// URL that opens Claude Code in a new terminal window. The URL can carry a working directory and a prompt to pre-fill. This lets you share a one-click starting point for a task: anyone with Claude Code installed who clicks the link sees a session open with the prompt already typed. The prompt is populated but not sent until you press Enter. Because a deep link is a URL, you can put one anywhere a link can go:
  • An incident runbook step that opens the affected service’s repo with a diagnostic prompt
  • A monitoring alert or dashboard that links to an investigation prompt for a specific metric
  • A README or wiki page that opens the project with an onboarding prompt
  • A CI failure notification that pre-fills the failing job’s name
This page covers how to build a link, embed one in a runbook or trigger it from the shell, and manage or disable handler registration on each platform.

​
How it works

The claude-cli:// prefix is a custom URL scheme that Claude Code registers with your operating system, similar to how mailto: links open your email client. The link can live on a web page, in a wiki, in a Slack message, or in any app that renders links. When you click one:
  1. The browser or app hands the URL to your operating system.
  2. The operating system recognizes the claude-cli:// prefix and starts Claude Code on your machine.
  3. A new terminal window opens with Claude Code running in the directory the link specified, and the link’s prompt text already in the input box.
  4. You read the prompt, edit it if you want, and press Enter to send it.
The link itself can be hosted anywhere, but the session always opens locally on the computer where you clicked. See Registration and supported platforms for which terminal emulator opens on each operating system.
The platform that displays the link must allow custom URL schemes. GitHub-rendered Markdown allows http and https but strips schemes like claude-cli:// in READMEs, issues, pull requests, and wikis. Only the link text shows, with no link behind it and the URL hidden. See Troubleshooting for a workaround.

​
What a launched session shows

A deep link never executes anything on its own. The link only chooses a directory and fills the prompt box. If you click a link from a page you do not trust, the prompt is still inert: nothing reaches the model until you read what was filled in and press Enter. When the session opens, a warning line below the input box reads Prompt from an external link and stays visible until you send or clear the prompt. For prompts over 1,000 characters, the warning includes the character count and tells you to scroll and review the full text before pressing Enter, since long prompts can push instructions off screen. Permission rules, CLAUDE.md, and trust prompts for the selected directory apply the same way as for any other session. Every deep link starts with claude-cli://open, which is the only path the handler accepts, followed by optional query parameters. The minimal form opens Claude Code in your home directory with an empty prompt:
To try a link without putting it on a page, paste it into your browser’s address bar or open it from the shell. Add parameters to control where the session starts and what the prompt box contains: cwd and repo are two ways to set the working directory. If you pass both, cwd takes precedence and repo is ignored, even if the cwd path does not exist. The following link points at a repository called acme/payments with a two-line diagnostic prompt. Replace acme/payments with your repository’s owner/name slug when you build your own:
Clicking it opens a new terminal window, starts Claude Code in your local clone of acme/payments, and fills the prompt box with the decoded text:
You can edit the prompt before pressing Enter to send it. If you have no local clone of the repository, the session opens in your home directory instead. See Choose between cwd and repo for how the local path is selected when you have multiple clones or worktrees.

​
Choose between cwd and repo

Use cwd when everyone who clicks the link has the project at the same absolute path, such as a standardized devcontainer or VM image. Use repo when the link is shared and each person clones to a different location. Claude Code resolves the slug to a local path as follows:
  • Each time you run claude in a Git repository, Claude Code records that directory’s path against the repository’s GitHub owner/name slug.
  • When a deep link arrives, repo opens whichever matching path you used most recently. Claude Code tracks multiple clones and worktrees separately, so it picks the one you worked in last.
  • The lookup only finds paths where you have already run Claude Code at least once.
  • The link does not change which branch is checked out. The session opens in whatever state that directory is currently in.
The welcome header shows which path it picked so you can confirm the right clone opened.

​
Examples

The sections below show two common ways to use a deep link: as a Markdown link in a document and as a command in a script or shell alias. A deep link in a runbook gives whoever is triaging a one-click way to start investigating in the right repository with a prepared prompt. The platform that renders the runbook must allow custom URL schemes. GitHub-rendered Markdown does not allow claude-cli://, so a deep link in a GitHub README, issue, or wiki shows only its label with no clickable link. See the troubleshooting note for a workaround. The prompt is part of the URL and must be URL-encoded. To produce the encoded value, pass your prompt text through encodeURIComponent in a browser console or any URL encoder. The example below adds an investigation entry point to an incident runbook for a service called web-gateway: