Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Um deep link é uma URL claude-cli:// que abre Claude Code em uma nova janela de terminal. A URL pode carregar um diretório de trabalho e um prompt para pré-preenchimento. Isso permite que você compartilhe um ponto de partida com um clique para uma tarefa: qualquer pessoa com Claude Code instalado que clique no link verá uma sessão aberta com o prompt já digitado. O prompt é preenchido, mas não é enviado até que você pressione Enter. Como um deep link é uma URL, você pode colocá-lo em qualquer lugar onde um link possa ir:
  • Uma etapa de runbook de incidente que abre o repositório do serviço afetado com um prompt de diagnóstico
  • Um alerta de monitoramento ou dashboard que vincula a um prompt de investigação para uma métrica específica
  • Uma página README ou wiki que abre o projeto com um prompt de integração
  • Uma notificação de falha de CI que pré-preenchimento o nome do trabalho que falhou
Esta página cobre como construir um link, incorporá-lo em um runbook ou acioná-lo a partir do shell, e gerenciar ou desabilitar o registro do handler em cada plataforma.
Deep links requerem Claude Code v2.1.91 ou posterior.

​
Como funciona

O prefixo claude-cli:// é um esquema de URL personalizado que Claude Code registra com seu sistema operacional, semelhante a como links mailto: abrem seu cliente de email. O link pode estar em uma página da web, em um wiki, em uma mensagem do Slack ou em qualquer aplicativo que renderize links. Quando você clica em um:
  1. O navegador ou aplicativo passa a URL para seu sistema operacional.
  2. O sistema operacional reconhece o prefixo claude-cli:// e inicia Claude Code em sua máquina.
  3. Uma nova janela de terminal abre com Claude Code executando no diretório que o link especificou, e o texto do prompt do link já está na caixa de entrada.
  4. Você lê o prompt, edita-o se desejar e pressiona Enter para enviá-lo.
O link em si pode ser hospedado em qualquer lugar, mas a sessão sempre abre localmente no computador onde você clicou. Veja Registro e plataformas suportadas para saber qual emulador de terminal abre em cada sistema operacional.
A plataforma que exibe o link deve permitir esquemas de URL personalizados. O Markdown renderizado pelo GitHub permite http e https, mas remove esquemas como claude-cli:// em READMEs, issues, pull requests e wikis. Apenas o texto do link é exibido, sem link por trás e a URL oculta. Veja Troubleshooting para uma solução alternativa.

​
O que uma sessão iniciada mostra

Um deep link nunca executa nada por conta própria. O link apenas escolhe um diretório e preenche a caixa de prompt. Se você clicar em um link de uma página em que não confia, o prompt ainda é inerte: nada chega ao modelo até que você leia o que foi preenchido e pressione Enter. Quando a sessão abre, um banner acima da entrada mostra que um link externo a iniciou e qual diretório foi selecionado. Para prompts com mais de 1.000 caracteres, o banner informa para você rolar e revisar o texto completo antes de pressionar Enter, já que prompts longos podem empurrar instruções para fora da tela. As regras de permissão, CLAUDE.md e prompts de confiança para o diretório selecionado se aplicam da mesma forma que para qualquer outra sessão. Cada deep link começa com claude-cli://open, que é o único caminho que o handler aceita, seguido por parâmetros de consulta opcionais. A forma mínima abre Claude Code em seu diretório inicial com um prompt vazio: 
claude-cli://open
Adicione parâmetros para controlar onde a sessão começa e o que a caixa de prompt contém:
ParâmetroDescrição
qTexto para pré-preenchimento na caixa de prompt. URL-encode o valor. Use %0A para quebras de linha em prompts de múltiplas linhas. Máximo de 5.000 caracteres.
cwdCaminho absoluto para usar como diretório de trabalho. Caminhos de rede e UNC são rejeitados.
repoUm slug owner/name do GitHub. Claude Code o resolve para um clone local que viu antes e começa lá. Se você não tiver um clone correspondente, a sessão abre em seu diretório inicial.
cwd e repo são duas maneiras de definir o diretório de trabalho. Se você passar ambos, cwd tem precedência e repo é ignorado, mesmo que o caminho cwd não exista. O link a seguir aponta para um repositório chamado acme/payments com um prompt de diagnóstico de duas linhas. Substitua acme/payments pelo slug owner/name do seu repositório quando construir o seu: 
claude-cli://open?repo=acme/payments&q=Investigate%20the%20failed%20deploy%20of%20payments-api.%0ACheck%20recent%20commits%20to%20main%20and%20the%20last%20successful%20build.
Clicar nele abre uma nova janela de terminal, inicia Claude Code em seu clone local de acme/payments e preenche a caixa de prompt com o texto decodificado: 
Investigate the failed deploy of payments-api.
Check recent commits to main and the last successful build.
Você pode editar o prompt antes de pressionar Enter para enviá-lo. Se você não tiver um clone local do repositório, a sessão abre em seu diretório inicial. Veja Escolher entre cwd e repo para saber como o caminho local é selecionado quando você tem múltiplos clones ou worktrees.

​
Escolher entre cwd e repo

Use cwd quando todos que clicarem no link tiverem o projeto no mesmo caminho absoluto, como um devcontainer padronizado ou imagem de VM. Use repo quando o link é compartilhado e cada pessoa clona para um local diferente. Claude Code resolve o slug para um caminho local da seguinte forma:
  • Cada vez que você executa claude em um repositório Git, o caminho do sistema de arquivos desse diretório é registrado contra o slug owner/name do GitHub do repositório.
  • Quando um deep link chega, repo abre qualquer caminho correspondente que você usou mais recentemente. Múltiplos clones e worktrees são rastreados separadamente, então ele escolhe aquele em que você trabalhou por último.
  • A busca apenas encontra caminhos onde você já executou Claude Code pelo menos uma vez.
  • O link não muda qual branch está verificado. A sessão abre no estado em que esse diretório está atualmente.
A sessão iniciada mostra qual caminho foi escolhido e quando esse clone buscou pela última vez do remoto, para que você possa dizer se está olhando para código obsoleto.

​
Exemplos

As seções abaixo mostram duas maneiras comuns de usar um deep link: como um link Markdown em um documento e como um comando em um script ou alias de shell. Um deep link em um runbook oferece a quem está triando uma maneira com um clique de começar a investigar no repositório correto com um prompt preparado. A plataforma que renderiza o runbook deve permitir esquemas de URL personalizados. O Markdown renderizado pelo GitHub não permite claude-cli://, então um deep link em um README, issue ou wiki do GitHub mostra apenas seu rótulo sem link clicável. Veja a nota de troubleshooting para uma solução alternativa. O prompt faz parte da URL e deve ser URL-codificado. Para produzir o valor codificado, passe seu texto de prompt através de encodeURIComponent em um console do navegador ou qualquer codificador de URL. O exemplo abaixo adiciona um ponto de entrada de investigação a um runbook de incidente para um serviço chamado web-gateway: 
## High 5xx rate on web-gateway

1. Acknowledge the page in PagerDuty.
2. [Open Claude Code in the gateway repo](claude-cli://open?repo=acme/web-gateway&q=5xx%20rate%20is%20elevated%20on%20web-gateway.%20Check%20recent%20deploys%2C%20error%20logs%20from%20the%20last%2030%20minutes%2C%20and%20open%20incidents%20in%20Linear.)
3. Post initial findings in #incident.
Para usar isso em seu próprio runbook, substitua acme/web-gateway pelo slug do repositório do seu serviço. Isso permite que engenheiros com Claude Code instalado e um clone local desse repositório cliquem na etapa 2 e comecem a investigar com o prompt pronto para enviar. Você também pode abrir um deep link a partir de um script de shell, alias ou automação em vez de clicar nele. Chame o comando de abertura de URL do seu sistema operacional com o link como argumento.
O comando open integrado passa a URL para o handler claude-cli:// registrado:
open "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"

​
Registro e plataformas suportadas

Claude Code registra o handler claude-cli:// com seu sistema operacional na primeira vez que você inicia uma sessão interativa no macOS, Linux e Windows. Você não executa um comando de instalação separado. O registro escreve apenas em locais de nível de usuário:
PlataformaLocalização do Handler
macOS~/Applications/Claude Code URL Handler.app
Linuxclaude-code-url-handler.desktop sob $XDG_DATA_HOME/applications, padronizando para ~/.local/share/applications
WindowsHKEY_CURRENT_USER\Software\Classes\claude-cli
O handler inicia Claude Code em um emulador de terminal detectado. No macOS, Claude Code lembra do terminal de sua sessão interativa mais recente e o reutiliza, suportando iTerm2, Ghostty, kitty, Alacritty, WezTerm e Terminal.app. No Linux, ele honra a variável de ambiente $TERMINAL, depois x-terminal-emulator, depois uma lista de emuladores comuns. No Windows, ele prefere Windows Terminal, depois PowerShell, depois cmd.exe. Para evitar o registro completamente, defina disableDeepLinkRegistration como "disable" em settings.json. Para impor isso em toda uma organização para que os usuários não possam reabilitá-lo, defina-o em managed settings.

​
Abrir uma aba do VS Code em vez de um terminal

A extensão do VS Code registra seu próprio handler em vscode://anthropic.claude-code/open, que abre uma aba do editor Claude Code em vez de uma janela de terminal. Veja Launch a VS Code tab from other tools para os parâmetros dessa URL.

​
Troubleshooting

O handler provavelmente não está registrado ainda. Inicie uma sessão claude interativa uma vez nessa máquina, saia e tente o link novamente. Se você estiver no Linux sem um ambiente de desktop, xdg-open pode não ter nada para despachar. Alguns renderizadores Markdown apenas permitem links http e https e removem outros esquemas de URL. O GitHub faz isso em READMEs, issues, pull requests e wikis: [label](claude-cli://...) é renderizado como apenas label, sem link e a URL removida. Nessas plataformas, coloque o deep link em um bloco de código para que os leitores possam ver a URL e colá-la na barra de endereços do navegador.

​
A sessão abre em meu diretório inicial em vez do repositório

O parâmetro repo apenas resolve para clones que Claude Code já viu. Execute claude dentro do clone uma vez para que seu caminho seja registrado, ou mude o link para usar cwd com um caminho absoluto. No macOS, inicie claude em seu terminal preferido uma vez e o próximo deep link o usará. No Linux, defina a variável de ambiente $TERMINAL para o nome do comando do seu emulador preferido. No Windows, a ordem é fixa: instale Windows Terminal se quiser que os links abram lá em vez de uma janela PowerShell ou cmd.exe.

​
Saiba mais

Essas páginas cobrem maneiras relacionadas de iniciar ou estender sessões Claude Code:
  • Skills: armazene um prompt de runbook longo como um /skill no repositório para que o parâmetro q do deep link apenas tenha que nomeá-lo
  • Non-interactive mode: execute Claude a partir de um script e capture a saída sem abrir um terminal