What are deep links? Launch a coding agent from a URL

Nov 3, 2026

A deep link is a URL that opens a coding agent with a prompt waiting in the box. How claude-cli, cursor, and codex links work, and what Grok documents.

A deep link is a URL that opens a coding agent on your machine and puts a prompt in the box. You read it. You send it yourself. The link does not run the agent.

It is not remote control from a phone. How to work with coding agents from your phone is a session that keeps running somewhere you can reach. A deep link starts, or fills, a local app because you opened a URL on that computer. It is also not a scheduled task. A schedule fires later. A deep link fires when someone clicks it.

How a deep link works

The URL uses a scheme the vendor registered with the operating system, the same idea as mailto:. The browser or a shell hands the URL to the OS. The OS starts the app. The app opens a session and drops the decoded text into the prompt.

Nothing is sent until you confirm. Claude Code shows a warning line, Prompt from an external link, until you send or clear it. Cursor says deeplinks never trigger automatic execution. Codex says the desktop app does not send the prompt for you. A link from a page you do not trust is still just text in a box, plus whatever directory the link selected.

Deep links in each tool

Claude Code, Cursor, and the Codex desktop app each document a scheme. Grok Build and Grok Bot do not document one.

	Claude Code	Codex	Cursor	Grok
Scheme	`claude-cli://open`	`codex://`	`cursor://anysphere.cursor-deeplink/` and `https://cursor.com/link/`	Not documented
Prompt parameter	`q`, URL-encoded, 5,000 characters max	`prompt` on `codex://new`	`text`, 10,000 characters max for the whole URL	Not documented
Working directory	`cwd`, or a GitHub `repo` slug	`path`, or `originUrl` to match a Git remote	Not documented as a directory parameter	Not documented
Sends on open	No. You press Enter	No. The text sits in the composer	No. You review and confirm	Not documented

Claude Code

claude-cli://open opens a new terminal window. Add q for the prompt. Use %0A for a newline. Add cwd for an absolute path, or repo for a GitHub owner/name slug. If both are present, cwd wins and repo is ignored, even when that path does not exist. cwd rejects network and UNC paths, .. segments, and invisible or bidirectional characters.

repo resolves to the clone or worktree where you most recently ran claude. No matching clone opens your home directory. The link does not change the checked-out branch. Prompts over 1,000 characters add the character count to the warning and tell you to scroll. Permission rules, CLAUDE.md, and trust prompts still apply.

The handler registers after you send something in an interactive session, a message or /help, or after you start agent view with claude agents in a trusted folder. Starting a session and sending nothing does not register it. On macOS the handler is ~/Applications/Claude Code URL Handler.app, and Claude Code reuses the last terminal it saw: iTerm2, Ghostty, kitty, Alacritty, WezTerm, or Terminal.app. On Linux the desktop file is claude-code-url-handler.desktop under $XDG_DATA_HOME/applications, defaulting to ~/.local/share/applications. $TERMINAL wins, then x-terminal-emulator. On Windows the key is HKCU\Software\Classes\claude-cli, and the order is Windows Terminal, then PowerShell, then cmd.exe.

Set disableDeepLinkRegistration to "disable" in settings.json to stop registration. Managed settings can enforce that. The setting covers claude-cli:// only. The VS Code extension has a separate handler, vscode://anthropic.claude-code/open. Claude Desktop uses claude:// for SSH sessions. Those are different schemes.

GitHub-rendered Markdown strips claude-cli:// links. Put the URL in a code block. From a shell, macOS uses open, Linux uses xdg-open, PowerShell uses Start-Process, and cmd.exe needs start "" plus the URL, because start treats the first quoted argument as a window title.

See Claude Code deep links.

OpenAI Codex

The ChatGPT desktop app keeps codex:// for compatibility. Query values are URL-encoded. The decoded prompt lands in the composer and is not sent.

codex://threads/new opens a new local chat. codex://new needs at least one of prompt, path, or originUrl, or the link does nothing. prompt is the composer text. path is an absolute local directory, and a valid path becomes the workspace. originUrl matches a workspace root by Git remote. If both path and originUrl are set, path wins. codex://threads/<threadId> opens that thread. codex://settings opens settings. codex://skills opens skills. codex://automations opens Scheduled with the create flow open, which is the scheduled tasks screen.

The shortcut to copy a chat’s deep link is Cmd+Opt+L on macOS, and Ctrl+Alt+L on Windows and Linux.

See the deep links section of the Codex command reference.

Cursor

A prompt link opens Cursor with the text filled in. You review it and confirm. The web form is https://cursor.com/link/prompt?text=.... The app form is cursor://anysphere.cursor-deeplink/prompt?text=.... Web links redirect to cursor.com.

A command link uses /command with name and text and creates a command from .cursor/commands after you confirm. A rule link uses /rule with name and text and creates a rule after you confirm. Those files are the same kind of shortcut the slash commands and rules entries describe. The maximum URL length is 10,000 characters. The page says to review a link before you share it, so a prompt with a secret does not leave your machine inside a URL.

See Cursor deeplinks.

Grok

Grok Build’s docs and Grok Bot’s docs do not describe a URL scheme that opens a session or fills a prompt. An x-grok-conv-id header on an API response is a conversation id for caching. It is not a link you open.

Details checked against each vendor’s documentation in November 2026.

A real example

A runbook step should open Claude Code on a repo you have already launched claude in, with a review prompt waiting. The repo value is a GitHub owner/name slug:

claude-cli://open?repo=flaviocopes/flaviocopes.com&q=Review%20open%20pull%20requests

The handler has to be registered on that machine first, by sending a message in an interactive session. The prompt stays in the box until Enter.

The same prompt as a Cursor web link:

https://cursor.com/link/prompt?text=Review%20open%20pull%20requests

And as a Codex desktop link, which needs prompt so codex://new does something:

codex://new?prompt=Review%20open%20pull%20requests

Add path only when you have an absolute directory to hand the app. The Codex page requires an absolute path.

When to use a deep link

Use one in a runbook, a README code block, or an alert, when the next step is “open the agent on this repo and start from this prompt.” The person who clicks still reads the prompt. That is the part worth keeping.

Use a slash command or a skill when the prompt is long and already lives in the repo. Claude Code’s deep link page points at skills for that: the URL only has to name the skill. Use a scheduled task when the run should start without a click.

Skip a deep link for a prompt that contains a token, a customer id, or a private URL. The text is in the query string. It will sit in browser history, chat logs, and anyone’s screenshot of the address bar.

Pitfalls

The link looks automatic and is not. Claude Code will not send it. Cursor will not execute it. Codex will not send it. You can still press Enter on a prompt you only skimmed. The warning line is there because the text came from outside the session.

repo fails closed to your home directory when Claude Code has never seen that clone. Run claude in the checkout once before you rely on the slug. Passing both cwd and repo silently ignores repo.

GitHub will not render a claude-cli:// link as a link. A README that depends on the click will show the label and drop the URL. A code block is the workaround the docs give.

Cursor’s 10,000 character cap is on the whole URL, after encoding. A long prompt encodes to something longer than the text you typed. Claude Code’s cap is 5,000 characters on q itself.

How to work with coding agents from your phone is remote control of a session. A deep link is a URL opened on the machine where the app runs.
Sessions are what the link opens, or the thread id a Codex link can point back at.
Scheduled agent tasks start work on a clock. codex://automations is the link that opens that screen.
Slash commands are the shorter prompt to put in a link when the full instructions already live in the repo.

Sessions: A session is a saved coding-agent conversation you can resume later. How Claude Code, Codex, the Cursor CLI and Grok Build store, name, resume and fork one.
Slash commands: Slash commands are the /name controls inside a coding agent session. How they work in Claude Code, Codex, Cursor and Grok Build, and how to add your own.
Scheduled agent tasks: A scheduled agent task reruns a saved prompt on a clock or an event, without you in the chat. How Claude Code, Codex, Cursor, and Grok set that up.

All AI glossary entries →

Follow @flaviocopes

Want me to talk about your product? You can sponsor this site.