A deep link opens Claude Code from a URL. The prompt pre-fills in the input box, but nothing runs until the engineer presses Enter. That safety property is deliberate: the link is a shortcut, not an executor.
Claude Code registers the claude-cli:// handler automatically the first time you start a session. You do not need to set it up manually.
Basic structure
claude-cli://open?q=PROMPT&cwd=PATH&repo=OWNER/NAMEURL-encode the query parameter values. The three parameters:
| Parameter | What it does |
|---|---|
q | Pre-fills the prompt text. Maximum 5,000 characters. |
cwd | Sets the working directory when opening Claude Code. Absolute path. |
repo | Resolves to the most-recently-used local clone of OWNER/NAME. If not found, prompts the user to clone. |
Use cwd when you know the path. Use repo when the path varies by machine.
Three real examples
PagerDuty incident response:
claude-cli://open?q=Payment+service+is+down.+Check+the+last+30+logs+for+errors+and+look+for+anything+unusual+in+recent+commits.&repo=acme/payment-servicePaste this URL into your PagerDuty runbook. When the alert fires, the on-call engineer clicks, Claude Code opens in the payment service directory with the context pre-filled.
CI failure link (generated by your CI script):
PROMPT="Build failed on commit $(git rev-parse --short HEAD). The failing test is: $FAILING_TEST. Read the test file and the function it tests, then explain why the test is failing."
ENCODED=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$PROMPT'))")
echo "claude-cli://open?q=${ENCODED}&cwd=$(pwd)"Post this URL in your Slack CI failure message. Engineers click through to a session already pointed at the failure.
Onboarding wiki:
claude-cli://open?q=I+just+cloned+this+repo.+Give+me+a+tour+of+the+architecture.+Read+CLAUDE.md+first+if+it+exists.&repo=acme/monorepoEmbed in your team wiki’s “Getting started” page. New engineers get a context-aware tour without writing a prompt from scratch.
Open from the terminal
When you cannot embed a URL (shell script, Makefile target):
# macOS
open "claude-cli://open?q=Investigate+the+slow+query+in+reports.rb&cwd=$(pwd)"
# Linux
xdg-open "claude-cli://open?q=Investigate+the+slow+query&cwd=$(pwd)"
# Windows (PowerShell)
Start-Process "claude-cli://open?q=Investigate+the+slow+query&cwd=$(pwd)"VS Code sibling
If the engineer uses the VS Code extension, the equivalent URI opens Claude Code in the editor panel instead of a new terminal:
vscode://anthropic.claude-code/open?prompt=PROMPT&cwd=PATHBoth handlers can coexist. The claude-cli:// scheme opens a terminal session; vscode:// opens the panel.
Disable registration
To prevent Claude Code from registering the URI handler (useful for locked-down machines or shared accounts):
{
"disableDeepLinkRegistration": "disable"
}Set this in user settings (~/.claude/settings.json) or managed settings to apply org-wide.
Footguns
GitHub Markdown strips claude-cli:// links. READMEs, issues, wiki pages, and pull request descriptions on GitHub.com strip non-https:// links for security reasons. A claude-cli:// URL in a GitHub issue will not be clickable. Use https:// landing pages that redirect to the deep link, or host runbooks outside GitHub Markdown.
The prompt length limit is 5,000 characters. Longer prompts are truncated silently. For incident prompts that need more context, inject it through a SessionStart hook or CLAUDE.md instead.
repo= picks the most recently opened local clone, not a canonical one. If an engineer has cloned the same repo to two different paths, Claude Code picks whichever was opened most recently. When absolute path matters, use cwd= with a fixed path or ensure engineers use a standard clone location.
Registration happens on first launch. A machine that has never run Claude Code does not have the handler registered. Clicking a claude-cli:// link before opening Claude Code once does nothing. Include a note in runbooks for engineers who are new to the tool.
When NOT to use deep links
- You need the prompt to execute automatically without review. Deep links pre-fill only. For fully automated execution, use Channels or the Agent SDK.
- Your runbook lives on GitHub. The URL will not render as a link.
- The context needed to investigate the issue changes per incident. Build the prompt programmatically via
claude -por the API, not a pre-baked URL. - You need to pass more than 5,000 characters of context. Use a SessionStart hook that injects context from a script instead.