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. When you click a deep link:
  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: