Iniciar sesiones desde enlaces

Abre una sesión de Claude Code en la terminal desde una URL. Inserta enlaces claude-cli:// en runbooks, alertas y paneles para que un clic abra Claude Code en el repositorio correcto con el prompt correcto.

Un enlace profundo es una URL claude-cli:// que abre Claude Code en una nueva ventana de terminal. La URL puede incluir un directorio de trabajo y un prompt para rellenar previamente.

El prompt se rellena, pero no se envía hasta que presionas Enter. Para que los enlaces se abran en una máquina, primero envía un prompt en una sesión interactiva de Claude Code en ella, de modo que Claude Code registre su controlador claude-cli://.

Como un enlace profundo es una URL, puedes ponerlo en cualquier lugar donde pueda ir un enlace:

• Un paso de un runbook de incidentes que abre el repositorio del servicio afectado con un prompt de diagnóstico
• Una alerta de monitoreo o un panel que enlaza a un prompt de investigación para una métrica específica
• Un README o una página wiki que abre el proyecto con un prompt de incorporación
• Una notificación de fallo de CI que rellena previamente el nombre del job que falló

Esta página explica cómo crear un enlace, insertarlo en un runbook o activarlo desde el shell, y administrar o deshabilitar el registro del controlador en cada plataforma.

Cómo funcionan los deep links

El prefijo claude-cli:// es un esquema de URL personalizado que Claude Code registra en tu sistema operativo, de forma similar a como los enlaces mailto: abren tu cliente de correo electrónico. Cuando haces clic en un deep link:

1. El navegador o la aplicación pasa la URL a tu sistema operativo.
2. El sistema operativo reconoce el prefijo claude-cli:// e inicia Claude Code en tu máquina.
3. Se abre una nueva ventana de terminal con Claude Code ejecutándose en el directorio que especificó el enlace, y con el texto del prompt del enlace ya en el cuadro de entrada.
4. Lees el prompt, lo editas si quieres y presionas Enter para enviarlo.

El enlace en sí puede estar alojado en cualquier lugar, pero la sesión siempre se abre localmente en la computadora donde hiciste clic. Consulta Registro y plataformas compatibles para saber qué emulador de terminal se abre en cada sistema operativo.

La plataforma que muestra el enlace debe permitir esquemas de URL personalizados. Para saber qué hace GitHub con ellos y cuál es la solución alternativa, consulta El enlace se muestra como texto sin formato en lugar de ser clicable.

Qué muestra una sesión iniciada

Un deep link nunca ejecuta nada por sí solo. El enlace solo elige un directorio y rellena el cuadro del prompt. Si haces clic en un enlace de una página en la que no confías, el prompt sigue siendo inerte: nada llega al modelo hasta que lees lo que se rellenó y presionas Enter.

Cuando se abre la sesión, una línea de advertencia debajo del cuadro de entrada muestra Prompt from an external link y permanece visible hasta que envíes o borres el prompt. Para prompts de más de 1,000 caracteres, la advertencia incluye el número de caracteres y te indica que te desplaces y revises el texto completo antes de presionar Enter, ya que los prompts largos pueden empujar instrucciones fuera de la pantalla. Las reglas de permisos, CLAUDE.md y las solicitudes de confianza para el directorio seleccionado se aplican de la misma manera que en cualquier otra sesión.

Crear un enlace

Un enlace profundo comienza con claude-cli://open, seguido de parámetros de consulta opcionales. La forma mínima abre Claude Code en tu directorio home con un prompt vacío:

claude-cli://open

Para probar un enlace sin ponerlo en una página, pégalo en la barra de direcciones de tu navegador o ábrelo desde el shell.

Agrega parámetros para controlar dónde se inicia la sesión y qué contiene el cuadro del prompt:

cwd y repo son dos formas de establecer el directorio de trabajo. Si pasas ambos, cwd tiene precedencia y repo se ignora, incluso si la ruta de cwd no existe.

El siguiente enlace apunta a un repositorio llamado acme/payments con un prompt de diagnóstico de dos líneas. Reemplaza acme/payments con el slug owner/name de tu repositorio cuando crees el tuyo:

claude-cli://open?repo=acme/payments&q=Investigate%20the%20failed%20deploy%20of%20payments-api.%0ACheck%20recent%20commits%20to%20main%20and%20the%20last%20successful%20build.

Al hacer clic en él, se abre una nueva ventana de terminal, se inicia Claude Code en tu clon local de acme/payments y se rellena el cuadro del prompt con el texto decodificado:

Investigate the failed deploy of payments-api.
Check recent commits to main and the last successful build.

Puedes editar el prompt antes de presionar Enter para enviarlo. Consulta Elegir entre cwd y repo para saber cómo se selecciona la ruta local cuando tienes varios clones o worktrees.

Elegir entre cwd y repo

Usa cwd cuando todas las personas que hagan clic en el enlace tengan el proyecto en la misma ruta absoluta, como en una imagen estandarizada de devcontainer o de VM.

Usa repo cuando el enlace se comparta y cada persona clone en una ubicación diferente. Claude Code resuelve el slug a una ruta local de la siguiente manera:

• repo abre el clon o worktree del repositorio enlazado donde ejecutaste claude más recientemente. Cada vez que ejecutas claude en un repositorio Git, Claude Code registra la ruta de ese directorio asociada al slug owner/name de GitHub del repositorio. Claude Code rastrea los clones y los worktrees por separado.
• El enlace no cambia la rama que está activa. La sesión se abre en el estado en que se encuentre ese directorio en ese momento.

El encabezado de bienvenida muestra qué ruta eligió para que puedas confirmar que se abrió el clon correcto.

Ejemplos

Las secciones a continuación muestran dos formas comunes de usar un enlace profundo: como un enlace Markdown en un documento y como un comando en un script o alias de shell.

Incrustar un enlace en un runbook

Un enlace profundo en un runbook le da a quien está triando una forma de un clic para comenzar a investigar en el repositorio correcto con un mensaje preparado. La plataforma que representa el runbook debe permitir esquemas de URL personalizados. El Markdown representado por GitHub no permite claude-cli://, por lo que un enlace profundo en un README, problema o wiki de GitHub muestra solo su etiqueta sin enlace clickeable. Consulte la nota de solución de problemas para obtener una solución alternativa.

El mensaje es parte de la URL y debe estar codificado en URL. Para producir el valor codificado, pase el texto del mensaje a través de encodeURIComponent en una consola del navegador o cualquier codificador de URL.

El ejemplo a continuación agrega un punto de entrada de investigación a un runbook de incidentes para un servicio llamado 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 esto en tu propio runbook, reemplaza acme/web-gateway con el slug del repositorio de tu servicio. Antes de que los ingenieros hagan clic en el paso 2, deben haber enviado un prompt en una sesión interactiva de Claude Code en su máquina y haber abierto Claude Code en su clon local.

Abrir un enlace desde el shell

También puedes abrir un enlace profundo desde un script de shell, alias o automatización en lugar de hacer clic en él. Llama al comando de apertura de URL de tu sistema operativo con el enlace como argumento. Estos comandos se basan en el controlador que Claude Code registra en la máquina.

[tab] macOS

El comando open integrado pasa la URL al controlador claude-cli:// registrado:

open "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"

Si tiene éxito, se abre una nueva ventana de terminal con Claude Code ejecutándose y el mensaje rellenado previamente.

[tab] Linux

La mayoría de los entornos de escritorio proporcionan xdg-open, que pasa la URL al controlador registrado:

xdg-open "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"

Si tiene éxito, se abre una nueva ventana de terminal con Claude Code ejecutándose y el mensaje rellenado previamente. Si el shell informa que xdg-open no se encuentra, consulte Solución de problemas.

[tab] Windows

En PowerShell, Start-Process pasa la URL al controlador registrado:

Start-Process "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"

En cmd.exe, start trata su primer argumento entrecomillado como un título de ventana, así que pase un título vacío antes de la URL:

start "" "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"

Si tiene éxito, se abre una nueva ventana de terminal con Claude Code ejecutándose y el mensaje rellenado previamente.

Registro y plataformas compatibles

Claude Code registra el controlador claude-cli:// con tu sistema operativo en macOS, Linux y Windows cuando haces cualquiera de estas acciones:

• Envías cualquier cosa a una sesión interactiva de claude, como un mensaje o /help. Iniciar una y no enviar nada no registra el controlador.
• Inicias Claude Code en la vista de agentes, por ejemplo con claude agents, en una carpeta en la que hayas confiado

No ejecutas un comando de instalación separado. El registro escribe solo en ubicaciones a nivel de usuario:

El controlador inicia Claude Code en un emulador de terminal detectado. En macOS, Claude Code recuerda la terminal de tu sesión interactiva más reciente y la reutiliza, compatible con iTerm2, Ghostty, kitty, Alacritty, WezTerm y Terminal.app. En Linux, respeta la variable de entorno $TERMINAL, luego x-terminal-emulator, luego una lista de emuladores comunes. En Windows, prefiere Windows Terminal, luego PowerShell, luego cmd.exe.

Para evitar el registro por completo, establece disableDeepLinkRegistration en "disable" en settings.json. Para aplicar esto en toda una organización para que los usuarios no puedan volver a habilitarlo, establécelo en configuración administrada en su lugar. El ajuste disableDeepLinkRegistration de Claude Code solo cubre los enlaces claude-cli://.

Abrir una pestaña de VS Code en lugar de una terminal

La extensión de VS Code registra su propio controlador en vscode://anthropic.claude-code/open, que abre una pestaña del editor de Claude Code en lugar de una ventana de terminal. Consulte Iniciar una pestaña de VS Code desde otras herramientas para los parámetros de esa URL.

Abrir una sesión de Claude Desktop en una conexión SSH

Claude Desktop gestiona sus propios enlaces claude://. Para abrir una sesión de Desktop en una máquina remota mediante SSH, consulta Abrir una sesión SSH desde un enlace.

Solución de problemas

Hacer clic en el enlace no hace nada

El controlador probablemente aún no está registrado. En una sesión interactiva, el registro ocurre cuando envías algo, no cuando la sesión comienza. Inicia una sesión claude interactiva en esa máquina, envía cualquier prompt, sal e intenta el enlace nuevamente. Si estás en Linux sin un entorno de escritorio, xdg-open puede no tener nada a lo que enviar.

xdg-open no se encuentra en Linux

El comando xdg-open es parte del paquete xdg-utils, que las imágenes de servidor mínimas, contenedores y distribuciones de WSL a menudo omiten. Instale xdg-utils con el gestor de paquetes de su distribución, por ejemplo sudo apt install xdg-utils, luego ejecute el comando nuevamente. Si el comando se ejecuta pero no se abre nada, xdg-open puede no tener un entorno de escritorio al que enviar; consulte Hacer clic en el enlace no hace nada.

El enlace se representa como texto sin formato en lugar de ser clickeable

Algunos representadores de Markdown solo permiten enlaces http y https y eliminan otros esquemas de URL. GitHub hace esto en READMEs, issues, pull requests y wikis: [label](claude-cli://...) se representa como label, sin enlace y con la URL eliminada. En estas plataformas, coloca el enlace profundo en un bloque de código para que los lectores puedan ver la URL y pegarla en la barra de direcciones de su navegador.

La sesión se abre en mi directorio de inicio en lugar del repositorio

El parámetro repo solo se resuelve a clones que Claude Code ya ha visto. Ejecute claude dentro del clon una vez para que Claude Code registre su ruta, o cambie el enlace para usar cwd con una ruta absoluta.

El enlace abre la terminal incorrecta

En macOS, inicie claude en su terminal preferida una vez y el siguiente enlace profundo la usará. En Linux, establezca la variable de entorno $TERMINAL en el nombre del comando de su emulador preferido. En Windows, el orden es fijo: instale Windows Terminal si desea que los enlaces se abran allí en lugar de en una ventana de PowerShell o cmd.exe.

Más información

Estas páginas cubren formas relacionadas de iniciar o extender sesiones de Claude Code:

• Skills: almacene un mensaje de runbook largo como un /skill en el repositorio para que el parámetro q del enlace profundo solo tenga que nombrarlo
• Modo no interactivo: ejecute Claude desde un script y capture la salida sin abrir una terminal