One click and Claude Code is already in the project

What it is and why it matters

You get the alert that something broke: a failed deploy, an error on your numbers page, a red test. The usual routine is long: open the terminal, go to the right folder, start Claude Code, remember what to ask and type it from scratch. Every single time.

A deep link cuts all of that down to one click. It's a link that starts with claude-cli:// and works like the mailto: links that open your email. Inside it you put the project folder and the request. You click it, and a new terminal window opens with Claude Code in that folder and the request already typed in the box. Nothing is sent until you press Enter.

It's for you if you work alone and keep running into the same three or four emergencies: the payment that won't go through, the build that breaks, the page that slows down. You prepare the link once, put it where the problem shows up, and when it happens you're already in the right place with the right question.

1. Turn it on once

There's nothing to install besides Claude Code. The link works with Claude Code in the terminal, on macOS, Linux and Windows. Claude Code registers the claude-cli:// link handler with the system by itself, the first time you send a request in an interactive session. If you open it and close it without typing anything, it doesn't register.

1. Open the terminal you normally use and type claude.
2. Send it any request, even just “hi”, and press Enter. From now on the link works on this computer.
3. To try it, paste claude-cli://open into your browser's address bar. Claude Code opens in your home folder, with an empty box.

2. What a link is made of

Every link starts with claude-cli://open. After the question mark you add the parameters, separated by &. There are three:

• q: the request to type into the box. It has to be URL-encoded (spaces become %20, line breaks %0A). 5,000 characters at most.
• cwd: the absolute path of the folder, for example /Users/yourname/projects/shop. It rejects network paths and paths containing “..”.
• repo: the GitHub repository name in the owner/name form. Claude Code opens the local copy where you most recently started claude. If it doesn't know any, it opens your home folder.

If you work alone on one computer, cwd is the simplest. repo is handy if you clone the same project in different places, but it only works after you've started claude at least once in that copy. If you put both, cwd wins. The link doesn't switch branches: you find the folder as it is.

Here's a complete link, for an example repository acme/shop, with a two-line request:

claude-cli://open?repo=acme/shop&q=Last%20night%27s%20deploy%20failed.%0ALook%20at%20the%20latest%20commits%20on%20main%20and%20tell%20me%20the%20cause%2C%20without%20changing%20anything.

When you click it, the box shows the plain text: “Last night's deploy failed.” and below it, on a new line, the request. The welcome header shows the path it picked, so you can check it's the right copy.

3. Have Claude build the link for you

Encoding accents, spaces and line breaks by hand is the fastest way to get it wrong. I ask Claude Code to do it. Copy this message, replace the parts between < > and remove the < > symbols:

Build me a Claude Code deep link that starts with claude-cli://open.
Folder: cwd=<absolute path of the project>
Request to pre-fill:
<the request, multiple lines are fine>
URL-encode the request the way encodeURIComponent does, with %0A for line breaks, and check it stays under 5,000 characters.
Give me the link ready to copy and, below it, the decoded text, so I can check it says exactly what I want.

If you'd rather do it yourself: open the browser console, type encodeURIComponent("your request") and paste the result after q=.

If the request is long, like a whole procedure, don't cram it into the link. Write it as a skill in the project, in the file .claude/skills/<name>/SKILL.md, and put only /<name> in the link. The link stays short and you edit the procedure in one place.

4. Where to put it

The link goes where the problem shows up. I use it in three places.

In your alerts or numbers page

If you have an internal page with errors or metrics, every row can have a “Fix with Claude” link next to it. You add it like this:

On the page <alerts page file>, next to each error add a “Fix with Claude” link.
The link is claude-cli://open with cwd=<absolute path of the project> and q set to this request, encoded with encodeURIComponent:
“Error <error name> happened at <time>. Find the cause in the code and the logs and propose a fix. Don't change anything before you've explained it to me.”
Take the name and the time from each row's data. Don't change anything else on the page.

The page that shows the link has to allow links that don't start with http. The link can live anywhere, online too, but the session always opens on the computer where you click.

In a project document

In a Markdown file you write [Fix the checkout](claude-cli://open?...). Careful though: GitHub strips these links in READMEs, issues, pull requests and wikis, and only the label is left. There, put the link in a code block: whoever reads it copies it and pastes it into the browser's address bar.

In a terminal command

The link also opens from the command line, so you can put it in an alias or a script. Each system has its own command:

macOS:   open "claude-cli://open?repo=acme/shop&q=review%20open%20PRs"
Linux:   xdg-open "claude-cli://open?repo=acme/shop&q=review%20open%20PRs"
Windows (PowerShell):   Start-Process "claude-cli://open?repo=acme/shop&q=review%20open%20PRs"
Windows (cmd.exe):   start "" "claude-cli://open?repo=acme/shop&q=review%20open%20PRs"

For an alias of your own, ask Claude Code:

Add an alias called <alias name> to my shell's configuration file.
It should open, with the right command for my system, a claude-cli://open link with cwd=<absolute path of the project> and this request, URL-encoded:
<the request>
Before saving, show me the line you're adding and the decoded text.

5. Before you press Enter

A link doesn't run anything by itself: it picks the folder and fills the box. Below it you see the warning “Prompt from an external link”, until you send or clear the text. Over 1,000 characters the warning also shows the count and asks you to scroll and read all of it: a long text can hide instructions off screen.

The rules stay the usual ones: the trust prompt for the folder, the permissions and your CLAUDE.md apply as in any other session. If a link comes from a page you don't know, read the request line by line before pressing Enter. If something feels off, clear it.

If instead you don't want your computer to open these links, put "disableDeepLinkRegistration": "disable" in your settings.json: Claude Code no longer registers the claude-cli:// link handler.

6. If it doesn't work

• You click and nothing happens: the handler isn't registered yet. Start claude, send any request, exit and try again. On Linux without a desktop environment, xdg-open may have nothing to hand the link to. If xdg-open is missing altogether, install the xdg-utils package.
• It opens in your home folder instead of the project: repo only finds copies where you've already started claude. Start it once in there, or switch to cwd with the absolute path.
• The wrong terminal opens: on macOS start claude once in the terminal you prefer; on Linux set $TERMINAL; on Windows install Windows Terminal if you want links to open there.

Common mistakes

• Trying the link before you've sent at least one request to Claude Code on that computer: the handler isn't there yet.
• Writing the request without encoding it: spaces, accents and line breaks break the link. Have Claude build it.
• Using a relative path in cwd: it needs the absolute path, and paths with “..” are rejected.
• Pressing Enter without reading, especially if you didn't write the link yourself.

Checklist

• I've sent at least one request to Claude Code on this computer.
• claude-cli://open pasted into the browser opens Claude Code.
• My link has cwd with the absolute path, or repo with a copy where I've already started claude.
• The request in q is encoded and the decoded text says exactly what I want.
• Before Enter I read the request, even when I wrote it myself.

Frequently asked questions