Deep Links

Embed a claude-cli:// URL in a README, doc, or alert, and one click opens Claude Code in that project folder with a pre-filled prompt. The prompt lands in the input box but is not sent automatically — you review it and press Enter.

tip

Works in Claude Code v2.1.91+. The handler registers automatically the first time you start an interactive session — no separate install command needed.

Where You Can Embed Them

It's a URL, so anywhere a link fits:

• Your project README — a "set up this repo" or "onboard a new contributor" starter prompt
• Monitoring alerts and dashboards — a prompt to investigate a specific metric
• CI failure notifications — the failed job name pre-filled
• Wikis, Notion, internal docs — frequent diagnostic and maintenance tasks

GitHub Markdown blocks claude-cli://

GitHub READMEs, issues, PRs, and wikis allow only http and https and strip other schemes. [label](claude-cli://...) renders just the label with the link gone. Workaround: put the URL in a code block so users can see it and paste it into their address bar themselves.

How It Works

[Click] → Browser hands off the URL → OS recognizes the claude-cli:// handler
→ Claude Code starts → New terminal in the specified directory + pre-filled prompt
→ You review and press Enter

The link itself can live anywhere, but the session always opens locally on the computer that clicked it.

Building the URL

Every deep link starts with claude-cli://open. Optional query parameters control the location and prompt:

Parameter	Description
q	Text to pre-fill in the input box. URL-encoding required. Newlines as %0A. Max 5,000 characters
cwd	Absolute path of the working directory. Network/UNC paths are rejected
repo	GitHub owner/name slug. Claude Code finds the local clone path you've used before and starts there. If not found, starts in the home directory

If both cwd and repo are provided, cwd wins.

Practical Example

A deep link to embed in your README — pre-filling a two-line diagnostic prompt in the acme/payments repo:

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

Click it and a new terminal opens in your local acme/payments clone with the input box showing:

Investigate the failed deploy of payments-api.
Check recent commits to main and the last successful build.

Already filled in. You review it once more and press Enter.

cwd vs repo

• cwd: When everyone has the project at the same absolute path (standardized devcontainer or VM image)
• repo: Shared links where clone locations differ per person. Claude Code finds the path where you last ran claude in that repo and starts there

repo only resolves the path if you've run claude at least once in that repo. For a repo it hasn't seen, it opens in the home directory.

Opening Deep Links from the Shell

Call from scripts, aliases, or automation:

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: (the first argument is treated as the window title, so pass an empty title first)

start "" "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"

Security — What If You Click an Untrusted Link?

The deep link itself executes no code. It only selects a directory and fills text into the input box. Nothing reaches the model until you press Enter.

When the session opens, a banner above the input box shows that an external link started it, and in which directory. For long prompts over 1,000 characters, it prompts you to scroll and review the whole thing before pressing Enter. Permission rules, CLAUDE.md, and directory trust prompts all work the same as in a normal session.

Disabling Handler Registration

To block registration org-wide or on your own machine, set disableDeepLinkRegistration: "disable" in settings.json. Enforce it org-wide via managed settings.

Handler locations:

Platform	Location
macOS	~/Applications/Claude Code URL Handler.app
Linux	~/.local/share/applications/claude-code-url-handler.desktop
Windows	HKEY_CURRENT_USER\Software\Classes\claude-cli

Troubleshooting

Symptom	Cause
Nothing happens on click	Handler not registered — run claude interactively once and retry. On Linux without a desktop environment, xdg-open can't dispatch
Link displays as plain text	A platform that strips claude-cli://, like GitHub Markdown. Put the URL in a code block for users to copy-paste
Opens in the home directory despite repo	No record of running claude in that clone — run claude once inside the clone to register the path
A different terminal opens than expected	macOS remembers the terminal where you last ran claude. Linux prioritizes the $TERMINAL environment variable. Windows uses a fixed order: Windows Terminal → PowerShell → cmd.exe

Opening as a VS Code Tab (Separate Handler)

The VS Code extension registers a separate vscode://anthropic.claude-code/open handler — a Claude Code editor tab opens instead of a terminal. See the official VS Code page.

Summary

• claude-cli://open?repo=owner/name&q=prompt is the basic format
• q must be URL-encoded, %0A for newlines, max 5,000 characters
• repo only works if you have a history of running claude in that repo
• Embed in READMEs, runbooks, and alerts to start work in one click
• The deep link itself executes no code — nothing reaches the model until you press Enter

This chapter is based on the official deep-links page.

---

Next chapter: Debugging Your Configuration →