Um clique e o Claude Code já está no projeto

O que é e porque importa

Chega-te o aviso de que algo partiu: um deploy falhado, um erro na tua página de números, um teste a vermelho. O caminho habitual é longo: abres o terminal, vais para a pasta certa, arrancas o Claude Code, lembras-te do que lhe pedir e escreves tudo de novo. Sempre.

Um deep link reduz tudo a um clique. É um link que começa por claude-cli:// e funciona como os links mailto: que abrem o email. Lá dentro pões a pasta do projeto e o pedido. Clicas, e abre-se uma nova janela do terminal com o Claude Code nessa pasta e o pedido já escrito na caixa. Nada é enviado até carregares em Enter.

É para ti se trabalhas sozinho e tens sempre as mesmas três ou quatro emergências: o pagamento que não passa, a build que rebenta, a página que fica lenta. Preparas o link uma vez, pões-no onde o problema aparece e, quando acontece, já estás no sítio certo com a pergunta certa.

1. Ativa-o uma única vez

Não há nada para instalar além do Claude Code. O link funciona com o Claude Code no terminal, em macOS, Linux e Windows. O Claude Code regista sozinho o gestor dos links claude-cli:// no sistema, na primeira vez que envias um pedido numa sessão interativa. Se o abrires e fechares sem escrever nada, não fica registado.

1. Abre o terminal que usas habitualmente e escreve claude.
2. Manda-lhe um pedido qualquer, nem que seja «olá», e carrega em Enter. A partir daqui o link funciona neste computador.
3. Para testar, cola claude-cli://open na barra de endereços do browser. O Claude Code abre na tua pasta pessoal, com a caixa vazia.

2. Como é feito um link

Todo o link começa por claude-cli://open. Depois do ponto de interrogação juntas os parâmetros, separados por &. São três:

• q: o pedido a escrever na caixa. Tem de ser codificado para URL (os espaços passam a %20, as mudanças de linha a %0A). No máximo 5.000 caracteres.
• cwd: o caminho absoluto da pasta, por exemplo /Users/teunome/projetos/shop. Recusa caminhos de rede e caminhos com «..».
• repo: o nome do repositório GitHub na forma dono/nome. O Claude Code abre a cópia local onde arrancaste o claude mais recentemente. Se não conhecer nenhuma, abre a tua pasta pessoal.

Se trabalhas sozinho num computador, o cwd é o mais simples. O repo dá jeito se clonas o mesmo projeto em sítios diferentes, mas só funciona depois de teres arrancado o claude pelo menos uma vez nessa cópia. Se puseres os dois, ganha o cwd. O link não muda de branch: encontras a pasta tal como está.

Aqui tens um link completo, para um repositório de exemplo acme/shop, com um pedido em duas linhas:

claude-cli://open?repo=acme/shop&q=O%20deploy%20desta%20noite%20falhou.%0AV%C3%AA%20os%20%C3%BAltimos%20commits%20na%20main%20e%20diz-me%20a%20causa%2C%20sem%20alterar%20nada.

Quando clicas, na caixa aparece o texto normal: «O deploy desta noite falhou.» e por baixo, noutra linha, o pedido. O caminho escolhido aparece no cabeçalho de boas-vindas, para confirmares que é a cópia certa.

3. Pede ao Claude para construir o link

Codificar à mão acentos, espaços e mudanças de linha é a forma mais rápida de errar. Eu peço ao Claude Code. Copia esta mensagem, troca as partes entre < > e tira os símbolos < >:

Constrói-me um deep link do Claude Code que comece por claude-cli://open.
Pasta: cwd=<caminho absoluto do projeto>
Pedido a pré-preencher:
<o pedido, pode ter várias linhas>
Codifica o pedido para URL como faz o encodeURIComponent, com %0A para as mudanças de linha, e confirma que fica abaixo dos 5.000 caracteres.
Dá-me o link pronto a copiar e, por baixo, o texto descodificado, para eu confirmar que diz exatamente o que quero.

Se preferires fazer sozinho: abre a consola do browser, escreve encodeURIComponent("o teu pedido") e cola o resultado depois de q=.

Se o pedido for longo, como um procedimento inteiro, não o enfies no link. Escreve-o como skill no projeto, no ficheiro .claude/skills/<nome>/SKILL.md, e no link põe só /<nome>. O link fica curto e o procedimento alteras num só sítio.

4. Onde o pôr

O link vai para onde o problema aparece. Eu uso-o em três sítios.

Na tua página de avisos ou de números

Se tens uma página interna com os erros ou as métricas, ao lado de cada linha cabe um link «Resolver com o Claude». Juntas assim:

Na página <ficheiro da página de avisos>, ao lado de cada erro junta um link «Resolver com o Claude».
O link é claude-cli://open com cwd=<caminho absoluto do projeto> e q igual a este pedido, codificado com encodeURIComponent:
«Aconteceu o erro <nome do erro> às <hora>. Encontra a causa no código e nos logs e propõe-me uma correção. Não alteres nada antes de ma explicares.»
O nome e a hora vêm dos dados de cada linha. Não alteres mais nada na página.

A página que mostra o link tem de permitir links que não comecem por http. O link pode estar em qualquer lado, também online, mas a sessão abre sempre no computador onde clicas.

Num documento do projeto

Num ficheiro Markdown escreves [Resolver o checkout](claude-cli://open?...). Atenção: o GitHub apaga estes links nos README, nas issues, nos pull requests e nas wikis, e fica só o nome. Aí põe o link num bloco de código: quem lê copia-o e cola-o na barra de endereços do browser.

Num comando do terminal

O link também abre pela linha de comandos, por isso podes pô-lo num alias ou num script. Cada sistema tem o seu comando:

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"

Para um alias teu, pede ao Claude Code:

Junta ao ficheiro de configuração da minha shell um alias chamado <nome do alias>.
Tem de abrir, com o comando certo para o meu sistema, um link claude-cli://open com cwd=<caminho absoluto do projeto> e este pedido, codificado para URL:
<o pedido>
Antes de guardar, mostra-me a linha que juntas e o texto descodificado.

5. Antes de carregares em Enter

Um link não executa nada sozinho: escolhe a pasta e preenche a caixa. Por baixo aparece o aviso «Prompt from an external link» (pedido vindo de um link externo), até enviares ou apagares o texto. Acima dos 1.000 caracteres o aviso mostra também quantos são e pede-te para deslizares e leres tudo: um texto longo pode esconder instruções fora do ecrã.

As regras continuam as de sempre: o pedido de confiança para a pasta, as permissões e o teu CLAUDE.md valem como em qualquer outra sessão. Se um link vier de uma página que não conheces, lê o pedido linha a linha antes de carregares em Enter. Se algo não bater certo, apaga-o.

Se, pelo contrário, não queres que o teu computador abra estes links, põe "disableDeepLinkRegistration": "disable" no teu settings.json: o Claude Code deixa de registar o gestor dos links claude-cli://.

6. Se não funcionar

• Clicas e não acontece nada: o gestor ainda não está registado. Arranca o claude, manda um pedido qualquer, sai e tenta outra vez. No Linux sem ambiente de trabalho, o xdg-open pode não ter nada para abrir. Se faltar mesmo o xdg-open, instala o pacote xdg-utils.
• Abre na tua pasta pessoal em vez do projeto: o repo só encontra as cópias onde já arrancaste o claude. Arranca-o uma vez lá dentro, ou passa para cwd com o caminho absoluto.
• Abre o terminal errado: no macOS arranca o claude uma vez no terminal que preferes; no Linux define $TERMINAL; no Windows instala o Windows Terminal se quiseres que os links abram lá.

Os erros mais comuns

• Testar o link antes de teres mandado pelo menos um pedido ao Claude Code nesse computador: o gestor ainda não existe.
• Escrever o pedido sem o codificar: espaços, acentos e mudanças de linha partem o link. Pede ao Claude para o construir.
• Usar um caminho relativo no cwd: é preciso o caminho absoluto, e os caminhos com «..» são recusados.
• Carregar em Enter sem ler, sobretudo se não foste tu a escrever o link.

Checklist

• Já mandei pelo menos um pedido ao Claude Code neste computador.
• claude-cli://open colado no browser abre o Claude Code.
• O meu link tem cwd com o caminho absoluto, ou repo com uma cópia onde já arranquei o claude.
• O pedido no q está codificado e o texto descodificado diz exatamente o que quero.
• Antes do Enter leio o pedido, mesmo quando fui eu a escrevê-lo.

Perguntas frequentes