Un clic e Claude Code è già nel progetto

Cos'è e perché conta

Ti arriva l'avviso che qualcosa si è rotto: un deploy fallito, un errore nella pagina coi numeri, un test rosso. Di solito il giro è lungo: apri il terminale, vai nella cartella giusta, avvii Claude Code, ti ricordi cosa chiedergli e lo scrivi da capo. Ogni volta.

Un deep link accorcia tutto a un clic. È un link che inizia con claude-cli:// e funziona come i link mailto: che aprono la mail. Dentro ci scrivi la cartella del progetto e la richiesta. Lo clicchi, e si apre una nuova finestra del terminale con Claude Code in quella cartella e la richiesta già scritta nella casella. Non parte niente finché non premi Invio.

È per te se lavori da solo e hai sempre le stesse tre o quattro emergenze: il pagamento che non passa, la build che salta, la pagina che va lenta. Prepari il link una volta, lo metti dove arriva il problema, e quando succede sei già nel posto giusto con la domanda giusta.

1. Attivalo una volta sola

Non c'è niente da installare a parte Claude Code. Il link funziona con Claude Code nel terminale, su macOS, Linux e Windows. Claude Code registra il gestore dei link claude-cli:// nel sistema da solo, la prima volta che invii una richiesta in una sessione interattiva. Se lo apri e lo chiudi senza scrivere niente, non si registra.

1. Apri il terminale che usi di solito e scrivi claude.
2. Mandagli una richiesta qualsiasi, anche solo «ciao», e premi Invio. Da qui il link è attivo su questo computer.
3. Per provarlo, incolla claude-cli://open nella barra degli indirizzi del browser. Si apre Claude Code nella tua cartella home, con la casella vuota.

2. Com'è fatto un link

Ogni link inizia con claude-cli://open. Dopo il punto di domanda aggiungi i parametri, separati da &. Sono tre:

• q: la richiesta da scrivere nella casella. Va codificata per l'URL (gli spazi diventano %20, gli a capo %0A). Al massimo 5.000 caratteri.
• cwd: il percorso assoluto della cartella, per esempio /Users/tuonome/progetti/shop. Rifiuta percorsi di rete e percorsi con «..».
• repo: il nome del repository GitHub nella forma proprietario/nome. Claude Code apre la copia locale in cui hai avviato claude più di recente. Se non ne conosce nessuna, apre la cartella home.

Se lavori da solo su un computer, cwd è il più semplice. repo è comodo se cloni lo stesso progetto in posti diversi, ma funziona solo dopo che hai avviato claude almeno una volta in quella copia. Se metti tutti e due, vince cwd. Il link non cambia branch: trovi la cartella com'è.

Ecco un link completo, per un repository d'esempio acme/shop, con una richiesta su due righe:

claude-cli://open?repo=acme/shop&q=Il%20deploy%20di%20stanotte%20%C3%A8%20fallito.%0AGuarda%20gli%20ultimi%20commit%20su%20main%20e%20dimmi%20la%20causa%2C%20senza%20modificare%20niente.

Quando lo clicchi, nella casella trovi il testo normale: «Il deploy di stanotte è fallito.» e sotto, a capo, la richiesta. Il percorso scelto lo vedi nell'intestazione di benvenuto, così controlli che sia la copia giusta.

3. Fatti costruire il link da Claude

Codificare a mano accenti, spazi e a capo è il modo più veloce per sbagliare. Io lo chiedo a Claude Code. Copia questo messaggio, cambia le parti tra < > e togli i simboli < >:

Costruiscimi un deep link di Claude Code che inizia con claude-cli://open.
Cartella: cwd=<percorso assoluto del progetto>
Richiesta da precompilare:
<la richiesta, anche su più righe>
Codifica la richiesta per un URL come fa encodeURIComponent, con %0A per andare a capo, e controlla che resti sotto i 5.000 caratteri.
Dammi il link pronto da copiare e, sotto, il testo decodificato, così verifico che dica esattamente quello che voglio.

Se preferisci farlo da solo: apri la console del browser, scrivi encodeURIComponent("la tua richiesta") e incolla il risultato dopo q=.

Se la richiesta è lunga, come una procedura intera, non infilarla nel link. Scrivila come skill nel progetto, nel file .claude/skills/<nome>/SKILL.md, e nel link metti solo /<nome>. Il link resta corto e la procedura la modifichi in un posto solo.

4. Dove metterlo

Il link va dove arriva il problema. Io lo uso in tre posti.

Nella tua pagina degli avvisi o dei numeri

Se hai una pagina interna con gli errori o le metriche, accanto a ogni riga ci sta un link «Sistema con Claude». Lo aggiungi così:

Nella pagina <file della pagina degli avvisi>, accanto a ogni errore aggiungi un link «Sistema con Claude».
Il link è claude-cli://open con cwd=<percorso assoluto del progetto> e q uguale a questa richiesta, codificata con encodeURIComponent:
«È successo l'errore <nome dell'errore> alle <ora>. Trova la causa nel codice e nei log e proponimi una correzione. Non modificare niente prima di avermela spiegata.»
Nome e ora vanno presi dai dati di ogni riga. Non cambiare altro della pagina.

La pagina che mostra il link deve permettere i link che non iniziano con http. Il link può stare ovunque, anche online, ma la sessione si apre sempre sul computer dove clicchi.

In un documento del progetto

In un file Markdown scrivi [Sistema il checkout](claude-cli://open?...). Attenzione però: GitHub cancella questi link nei README, nelle issue, nelle pull request e nelle wiki, e resta solo il nome. Lì metti il link in un blocco di codice: chi legge lo copia e lo incolla nella barra degli indirizzi del browser.

In un comando del terminale

Il link si apre anche da riga di comando, quindi puoi metterlo in un alias o in uno script. Su ogni sistema c'è il suo 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"

Per un alias tuo, chiedilo a Claude Code:

Aggiungi al file di configurazione della mia shell un alias chiamato <nome dell'alias>.
Deve aprire con il comando giusto per il mio sistema un link claude-cli://open con cwd=<percorso assoluto del progetto> e questa richiesta, codificata per l'URL:
<la richiesta>
Prima di salvare mostrami la riga che aggiungi e il testo decodificato.

5. Prima di premere Invio

Un link non esegue niente da solo: sceglie la cartella e riempie la casella. Sotto compare l'avviso «Prompt from an external link» (richiesta da un link esterno), finché non invii o cancelli il testo. Sopra i 1.000 caratteri l'avviso mostra anche quanti sono e ti chiede di scorrere e leggere tutto: un testo lungo può nascondere istruzioni fuori dallo schermo.

Le regole restano quelle di sempre: la richiesta di fiducia per la cartella, i permessi e il tuo CLAUDE.md valgono come in qualsiasi altra sessione. Se un link arriva da una pagina che non conosci, leggi la richiesta riga per riga prima di premere Invio. Se non ti torna, cancellala.

Se invece non vuoi che il tuo computer apra questi link, metti "disableDeepLinkRegistration": "disable" nel tuo settings.json: Claude Code non registra più il gestore dei link claude-cli://.

6. Se non funziona

• Clicchi e non succede niente: il gestore non è ancora registrato. Avvia claude, manda una richiesta qualsiasi, esci e riprova. Su Linux senza ambiente desktop xdg-open potrebbe non avere niente da aprire. Se manca proprio xdg-open, installa il pacchetto xdg-utils.
• Si apre nella cartella home invece che nel progetto: repo trova solo le copie dove hai già avviato claude. Avvialo una volta lì dentro, oppure passa a cwd con il percorso assoluto.
• Si apre il terminale sbagliato: su macOS avvia claude una volta nel terminale che preferisci; su Linux imposta $TERMINAL; su Windows installa Windows Terminal, se vuoi che i link si aprano lì.

Gli errori più comuni

• Provare il link prima di aver mandato almeno una richiesta a Claude Code su quel computer: il gestore non c'è ancora.
• Scrivere la richiesta senza codificarla: spazi, accenti e a capo rompono il link. Fattelo costruire da Claude.
• Usare un percorso relativo in cwd: serve il percorso assoluto, e i percorsi con «..» vengono rifiutati.
• Premere Invio senza leggere, soprattutto se il link non l'hai scritto tu.

Checklist

• Ho mandato almeno una richiesta a Claude Code su questo computer.
• claude-cli://open incollato nel browser apre Claude Code.
• Il mio link ha cwd con il percorso assoluto, oppure repo con una copia dove ho già avviato claude.
• La richiesta in q è codificata e il testo decodificato dice esattamente quello che voglio.
• Prima di Invio leggo la richiesta, anche quando l'ho scritta io.

Domande frequenti