Un clic y Claude Code ya está en el proyecto

Qué es y por qué importa

Te llega el aviso de que algo se ha roto: un deploy fallido, un error en tu página de números, un test en rojo. El camino de siempre es largo: abres la terminal, vas a la carpeta correcta, arrancas Claude Code, recuerdas qué pedirle y lo escribes desde cero. Cada vez.

Un deep link lo reduce todo a un clic. Es un enlace que empieza por claude-cli:// y funciona como los enlaces mailto: que abren el correo. Dentro pones la carpeta del proyecto y la petición. Haces clic y se abre una nueva ventana de terminal con Claude Code en esa carpeta y la petición ya escrita en la casilla. No se envía nada hasta que pulsas Enter.

Es para ti si trabajas solo y siempre te tocan las mismas tres o cuatro emergencias: el pago que no pasa, la build que se rompe, la página que va lenta. Preparas el enlace una vez, lo pones donde aparece el problema y, cuando pasa, ya estás en el sitio correcto con la pregunta correcta.

1. Actívalo una sola vez

No hay nada que instalar aparte de Claude Code. El enlace funciona con Claude Code en la terminal, en macOS, Linux y Windows. Claude Code registra el gestor de enlaces claude-cli:// en el sistema él solo, la primera vez que envías una petición en una sesión interactiva. Si lo abres y lo cierras sin escribir nada, no se registra.

1. Abre la terminal que usas siempre y escribe claude.
2. Mándale una petición cualquiera, aunque sea «hola», y pulsa Enter. A partir de aquí el enlace funciona en este ordenador.
3. Para probarlo, pega claude-cli://open en la barra de direcciones del navegador. Se abre Claude Code en tu carpeta personal, con la casilla vacía.

2. Cómo está hecho un enlace

Todo enlace empieza por claude-cli://open. Después del signo de interrogación añades los parámetros, separados por &. Son tres:

• q: la petición que se escribe en la casilla. Hay que codificarla para URL (los espacios pasan a %20, los saltos de línea a %0A). Como máximo 5.000 caracteres.
• cwd: la ruta absoluta de la carpeta, por ejemplo /Users/tunombre/proyectos/shop. Rechaza rutas de red y rutas con «..».
• repo: el nombre del repositorio de GitHub con la forma propietario/nombre. Claude Code abre la copia local donde arrancaste claude por última vez. Si no conoce ninguna, abre tu carpeta personal.

Si trabajas solo en un ordenador, cwd es lo más sencillo. repo es cómodo si clonas el mismo proyecto en sitios distintos, pero solo funciona después de haber arrancado claude al menos una vez en esa copia. Si pones los dos, gana cwd. El enlace no cambia de rama: encuentras la carpeta tal como está.

Aquí tienes un enlace completo, para un repositorio de ejemplo acme/shop, con una petición en dos líneas:

claude-cli://open?repo=acme/shop&q=El%20deploy%20de%20anoche%20fall%C3%B3.%0AMira%20los%20%C3%BAltimos%20commits%20en%20main%20y%20dime%20la%20causa%2C%20sin%20modificar%20nada.

Cuando haces clic, en la casilla aparece el texto normal: «El deploy de anoche falló.» y debajo, en otra línea, la petición. La ruta elegida la ves en la cabecera de bienvenida, así compruebas que es la copia correcta.

3. Pídele a Claude que construya el enlace

Codificar a mano tildes, espacios y saltos de línea es la forma más rápida de equivocarse. Yo se lo pido a Claude Code. Copia este mensaje, cambia las partes entre < > y quita los símbolos < >:

Constrúyeme un deep link de Claude Code que empiece por claude-cli://open.
Carpeta: cwd=<ruta absoluta del proyecto>
Petición para rellenar:
<la petición, puede ir en varias líneas>
Codifica la petición para URL como hace encodeURIComponent, con %0A para los saltos de línea, y comprueba que se quede por debajo de 5.000 caracteres.
Dame el enlace listo para copiar y, debajo, el texto decodificado, para comprobar que dice exactamente lo que quiero.

Si prefieres hacerlo tú: abre la consola del navegador, escribe encodeURIComponent("tu petición") y pega el resultado después de q=.

Si la petición es larga, como un procedimiento entero, no la metas en el enlace. Escríbela como skill en el proyecto, en el archivo .claude/skills/<nombre>/SKILL.md, y en el enlace pon solo /<nombre>. El enlace queda corto y el procedimiento lo cambias en un solo sitio.

4. Dónde ponerlo

El enlace va donde aparece el problema. Yo lo uso en tres sitios.

En tu página de avisos o de números

Si tienes una página interna con los errores o las métricas, al lado de cada fila cabe un enlace «Arreglar con Claude». Lo añades así:

En la página <archivo de la página de avisos>, al lado de cada error añade un enlace «Arreglar con Claude».
El enlace es claude-cli://open con cwd=<ruta absoluta del proyecto> y q igual a esta petición, codificada con encodeURIComponent:
«Ha ocurrido el error <nombre del error> a las <hora>. Encuentra la causa en el código y en los logs y propónme una corrección. No modifiques nada antes de habérmela explicado.»
El nombre y la hora salen de los datos de cada fila. No cambies nada más de la página.

La página que muestra el enlace tiene que permitir enlaces que no empiezan por http. El enlace puede estar en cualquier sitio, también online, pero la sesión se abre siempre en el ordenador donde haces clic.

En un documento del proyecto

En un archivo Markdown escribes [Arreglar el checkout](claude-cli://open?...). Ojo: GitHub borra estos enlaces en los README, las issues, las pull requests y las wikis, y solo queda el nombre. Ahí pon el enlace en un bloque de código: quien lo lee lo copia y lo pega en la barra de direcciones del navegador.

En un comando de la terminal

El enlace también se abre desde la línea de comandos, así que puedes meterlo en un alias o en un script. Cada sistema tiene su 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 un alias tuyo, pídeselo a Claude Code:

Añade al archivo de configuración de mi shell un alias llamado <nombre del alias>.
Tiene que abrir, con el comando adecuado para mi sistema, un enlace claude-cli://open con cwd=<ruta absoluta del proyecto> y esta petición, codificada para URL:
<la petición>
Antes de guardar, enséñame la línea que añades y el texto decodificado.

5. Antes de pulsar Enter

Un enlace no ejecuta nada por sí solo: elige la carpeta y rellena la casilla. Debajo aparece el aviso «Prompt from an external link» (petición desde un enlace externo), hasta que envías o borras el texto. Por encima de 1.000 caracteres el aviso muestra también cuántos son y te pide que te desplaces y lo leas todo: un texto largo puede esconder instrucciones fuera de la pantalla.

Las reglas son las de siempre: la pregunta de confianza para la carpeta, los permisos y tu CLAUDE.md valen como en cualquier otra sesión. Si un enlace llega de una página que no conoces, lee la petición línea a línea antes de pulsar Enter. Si algo no te cuadra, bórrala.

Si en cambio no quieres que tu ordenador abra estos enlaces, pon "disableDeepLinkRegistration": "disable" en tu settings.json: Claude Code deja de registrar el gestor de enlaces claude-cli://.

6. Si no funciona

• Haces clic y no pasa nada: el gestor aún no está registrado. Arranca claude, manda una petición cualquiera, sal y vuelve a probar. En Linux sin entorno de escritorio, xdg-open puede no tener nada que abrir. Si falta xdg-open, instala el paquete xdg-utils.
• Se abre en tu carpeta personal en lugar del proyecto: repo solo encuentra las copias donde ya arrancaste claude. Arráncalo una vez ahí dentro o pasa a cwd con la ruta absoluta.
• Se abre la terminal equivocada: en macOS arranca claude una vez en la terminal que prefieras; en Linux define $TERMINAL; en Windows instala Windows Terminal si quieres que los enlaces se abran ahí.

Errores comunes

• Probar el enlace antes de haber mandado al menos una petición a Claude Code en ese ordenador: el gestor todavía no existe.
• Escribir la petición sin codificarla: espacios, tildes y saltos de línea rompen el enlace. Pide a Claude que lo construya.
• Usar una ruta relativa en cwd: hace falta la ruta absoluta, y las rutas con «..» se rechazan.
• Pulsar Enter sin leer, sobre todo si el enlace no lo has escrito tú.

Lista de comprobación

• He mandado al menos una petición a Claude Code en este ordenador.
• claude-cli://open pegado en el navegador abre Claude Code.
• Mi enlace tiene cwd con la ruta absoluta, o repo con una copia donde ya he arrancado claude.
• La petición en q está codificada y el texto decodificado dice exactamente lo que quiero.
• Antes de Enter leo la petición, incluso cuando la he escrito yo.

Preguntas frecuentes