Lancer des sessions à partir de liens

Ouvrez une session Claude Code dans le terminal à partir d'une URL. Intégrez des liens claude-cli:// dans des runbooks, des alertes et des tableaux de bord pour qu'un clic ouvre Claude Code dans le bon dépôt avec le bon prompt.

Un lien profond (deep link) est une URL claude-cli:// qui ouvre Claude Code dans une nouvelle fenêtre de terminal. L'URL peut contenir un répertoire de travail et un prompt à pré-remplir.

Le prompt est renseigné mais n'est pas envoyé tant que vous n'appuyez pas sur Enter. Pour que les liens s'ouvrent sur une machine, envoyez d'abord un prompt dans une session interactive de Claude Code sur celle-ci, afin que Claude Code enregistre son gestionnaire claude-cli://.

Comme un lien profond est une URL, vous pouvez le placer partout où un lien peut figurer :

• Une étape d'un runbook d'incident qui ouvre le dépôt du service concerné avec un prompt de diagnostic
• Une alerte de monitoring ou un tableau de bord qui renvoie vers un prompt d'investigation pour une métrique spécifique
• Un README ou une page wiki qui ouvre le projet avec un prompt d'onboarding
• Une notification d'échec de CI qui pré-remplit le nom du job en échec

Cette page explique comment créer un lien, l'intégrer dans un runbook ou le déclencher depuis le shell, et gérer ou désactiver l'enregistrement du gestionnaire sur chaque plateforme.

Fonctionnement des liens profonds

Le préfixe claude-cli:// est un schéma d'URL personnalisé que Claude Code enregistre auprès de votre système d'exploitation, de la même manière que les liens mailto: ouvrent votre client de messagerie. Lorsque vous cliquez sur un lien profond :

1. Le navigateur ou l'application transmet l'URL à votre système d'exploitation.
2. Le système d'exploitation reconnaît le préfixe claude-cli:// et démarre Claude Code sur votre machine.
3. Une nouvelle fenêtre de terminal s'ouvre avec Claude Code en cours d'exécution dans le répertoire spécifié par le lien, et le texte du prompt du lien déjà présent dans la zone de saisie.
4. Vous lisez le prompt, le modifiez si vous le souhaitez, puis appuyez sur Enter pour l'envoyer.

Le lien lui-même peut être hébergé n'importe où, mais la session s'ouvre toujours localement sur l'ordinateur sur lequel vous avez cliqué. Consultez Enregistrement et plateformes prises en charge pour savoir quel émulateur de terminal s'ouvre sur chaque système d'exploitation.

La plateforme qui affiche le lien doit autoriser les schémas d'URL personnalisés. Pour savoir ce que GitHub en fait et comment contourner le problème, consultez Le lien s'affiche en texte brut au lieu d'être cliquable.

Ce qu'affiche une session lancée

Un lien profond n'exécute jamais rien de lui-même. Le lien se contente de choisir un répertoire et de remplir la zone de prompt. Si vous cliquez sur un lien provenant d'une page à laquelle vous ne faites pas confiance, le prompt reste inerte : rien n'atteint le modèle tant que vous n'avez pas lu ce qui a été rempli et appuyé sur Enter.

Lorsque la session s'ouvre, une ligne d'avertissement sous la zone de saisie indique Prompt from an external link et reste visible jusqu'à ce que vous envoyiez ou effaciez le prompt. Pour les prompts de plus de 1 000 caractères, l'avertissement inclut le nombre de caractères et vous invite à faire défiler et relire le texte complet avant d'appuyer sur Enter, car les prompts longs peuvent repousser des instructions hors de l'écran. Les règles de permission, CLAUDE.md et les demandes de confiance pour le répertoire sélectionné s'appliquent de la même manière que pour toute autre session.

Créer un lien

Un lien profond commence par claude-cli://open, suivi de paramètres de requête facultatifs. La forme minimale ouvre Claude Code dans votre répertoire personnel avec un prompt vide :

claude-cli://open

Pour tester un lien sans le placer sur une page, collez-le dans la barre d'adresse de votre navigateur ou ouvrez-le depuis le shell.

Ajoutez des paramètres pour contrôler l'endroit où la session démarre et le contenu de la zone de prompt :

cwd et repo sont deux façons de définir le répertoire de travail. Si vous passez les deux, cwd a priorité et repo est ignoré, même si le chemin cwd n'existe pas.

Le lien suivant pointe vers un dépôt appelé acme/payments avec un prompt de diagnostic sur deux lignes. Remplacez acme/payments par le slug owner/name de votre dépôt lorsque vous créez le vôtre :

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

Un clic sur ce lien ouvre une nouvelle fenêtre de terminal, démarre Claude Code dans votre clone local de acme/payments et remplit la zone de prompt avec le texte décodé :

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

Vous pouvez modifier le prompt avant d'appuyer sur Enter pour l'envoyer. Consultez Choisir entre cwd et repo pour savoir comment le chemin local est sélectionné lorsque vous avez plusieurs clones ou worktrees.

Choisir entre cwd et repo

Utilisez cwd lorsque toutes les personnes qui cliquent sur le lien disposent du projet au même chemin absolu, par exemple avec un devcontainer ou une image de VM standardisés.

Utilisez repo lorsque le lien est partagé et que chaque personne clone le dépôt à un emplacement différent. Claude Code résout le slug en un chemin local de la façon suivante :

• repo ouvre le clone ou le worktree du dépôt lié dans lequel vous avez exécuté claude le plus récemment. Chaque fois que vous exécutez claude dans un dépôt Git, Claude Code enregistre le chemin de ce répertoire en l'associant au slug GitHub owner/name du dépôt. Claude Code suit les clones et les worktrees séparément.
• Le lien ne modifie pas la branche extraite. La session s'ouvre dans l'état actuel de ce répertoire, quel qu'il soit.

L'en-tête de bienvenue indique le chemin choisi afin que vous puissiez vérifier que le bon clone s'est ouvert.

Exemples

Les sections ci-dessous montrent deux façons courantes d'utiliser un lien profond : comme un lien Markdown dans un document et comme une commande dans un script ou un alias shell.

Intégrer un lien dans un runbook

Un lien profond dans un runbook donne à celui qui trie un moyen en un clic de commencer à enquêter dans le bon dépôt avec une invite préparée. La plateforme qui affiche le runbook doit autoriser les schémas d'URL personnalisés. Le Markdown rendu par GitHub n'autorise pas claude-cli://, donc un lien profond dans un README, un problème ou un wiki GitHub affiche uniquement son étiquette sans lien cliquable. Consultez la note de dépannage pour une solution de contournement.

L'invite fait partie de l'URL et doit être encodée en URL. Pour produire la valeur encodée, passez votre texte d'invite par encodeURIComponent dans une console de navigateur ou n'importe quel encodeur d'URL.

L'exemple ci-dessous ajoute un point d'entrée d'investigation à un runbook d'incident pour un service appelé 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.

Pour utiliser ceci dans votre propre runbook, remplacez acme/web-gateway par le slug du dépôt de votre service. Avant que les ingénieurs cliquent sur l'étape 2, le gestionnaire claude-cli:// doit être enregistré sur leur machine, et ils doivent avoir exécuté claude dans leur clone local ou leur worktree.

Ouvrir un lien à partir du shell

Vous pouvez également ouvrir un lien profond à partir d'un script shell, d'un alias ou d'une automatisation plutôt que de cliquer dessus. Appelez la commande d'ouverture d'URL de votre système d'exploitation avec le lien comme argument. Ces commandes s'appuient sur le gestionnaire que Claude Code enregistre sur la machine.

[tab] macOS

La commande open intégrée transmet l'URL au gestionnaire claude-cli:// enregistré :

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

En cas de succès, une nouvelle fenêtre de terminal s'ouvre avec Claude Code en cours d'exécution et l'invite pré-remplie.

[tab] Linux

La plupart des environnements de bureau fournissent xdg-open, qui transmet l'URL au gestionnaire enregistré :

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

En cas de succès, une nouvelle fenêtre de terminal s'ouvre avec Claude Code en cours d'exécution et l'invite pré-remplie. Si le shell signale que xdg-open n'est pas trouvé, consultez Dépannage.

[tab] Windows

Dans PowerShell, Start-Process transmet l'URL au gestionnaire enregistré :

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

Dans cmd.exe, start traite son premier argument entre guillemets comme un titre de fenêtre, donc passez un titre vide avant l'URL :

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

En cas de succès, une nouvelle fenêtre de terminal s'ouvre avec Claude Code en cours d'exécution et l'invite pré-remplie.

Enregistrement et plateformes prises en charge

Claude Code enregistre le gestionnaire claude-cli:// auprès de votre système d'exploitation sur macOS, Linux et Windows lorsque vous effectuez l'une de ces actions :

• Envoyer quoi que ce soit à une session claude interactive, comme un message ou /help. En démarrer une sans rien envoyer n'enregistre pas le gestionnaire.
• Démarrer Claude Code dans la vue des agents, par exemple avec claude agents, dans un dossier que vous avez approuvé

Vous n'exécutez pas de commande d'installation séparée. L'enregistrement écrit uniquement dans des emplacements au niveau de l'utilisateur :

Le gestionnaire lance Claude Code dans un émulateur de terminal détecté. Sur macOS, Claude Code se souvient du terminal de votre session interactive la plus récente et le réutilise, en prenant en charge iTerm2, Ghostty, kitty, Alacritty, WezTerm et Terminal.app. Sur Linux, il honore la variable d'environnement $TERMINAL, puis x-terminal-emulator, puis une liste d'émulateurs courants. Sur Windows, il préfère Windows Terminal, puis PowerShell, puis cmd.exe.

Pour empêcher complètement l'enregistrement, définissez disableDeepLinkRegistration sur "disable" dans settings.json. Pour appliquer ceci dans toute une organisation afin que les utilisateurs ne puissent pas le réactiver, définissez-le dans les paramètres gérés à la place. Le paramètre disableDeepLinkRegistration de Claude Code couvre uniquement les liens claude-cli://.

Ouvrir un onglet VS Code au lieu d'un terminal

L'extension VS Code enregistre son propre gestionnaire à vscode://anthropic.claude-code/open, qui ouvre un onglet de l'éditeur Claude Code plutôt qu'une fenêtre de terminal. Consultez Lancer un onglet VS Code à partir d'autres outils pour les paramètres de cette URL.

Ouvrir une session Claude Desktop sur une connexion SSH

Claude Desktop gère ses propres liens claude://. Pour ouvrir une session Desktop sur une machine distante via SSH, consultez Ouvrir une session SSH à partir d'un lien.

Dépannage

Cliquer sur le lien ne fait rien

Le gestionnaire n'est probablement pas encore enregistré. Dans une session interactive, l'enregistrement se produit lorsque vous envoyez quelque chose, et non au démarrage de la session. Démarrez une session claude interactive sur cette machine, envoyez un prompt quelconque, quittez, et réessayez le lien. Si vous êtes sur Linux sans environnement de bureau, xdg-open n'a peut-être rien à dispatcher.

xdg-open n'est pas trouvé sur Linux

La commande xdg-open fait partie du paquet xdg-utils, que les images serveur minimales, les conteneurs et les distributions WSL omettent souvent. Installez xdg-utils avec le gestionnaire de paquets de votre distribution, par exemple sudo apt install xdg-utils, puis exécutez la commande à nouveau. Si la commande s'exécute ensuite mais que rien ne s'ouvre, xdg-open n'a peut-être pas d'environnement de bureau pour dispatcher ; voir Cliquer sur le lien ne fait rien.

Le lien s'affiche en tant que texte brut au lieu d'être cliquable

Certains moteurs de rendu Markdown n'autorisent que les liens http et https et suppriment les autres schémas d'URL. GitHub le fait dans les README, les issues, les pull requests et les wikis : [label](claude-cli://...) s'affiche comme label, sans lien et l'URL supprimée. Sur ces plateformes, mettez le lien profond dans un bloc de code afin que les lecteurs puissent voir l'URL et la coller dans la barre d'adresse de leur navigateur.

La session s'ouvre dans mon répertoire personnel au lieu du dépôt

Le paramètre repo ne résout que les clones que Claude Code a déjà vus. Exécutez claude à l'intérieur du clone une fois pour que Claude Code enregistre son chemin, ou basculez le lien pour utiliser cwd avec un chemin absolu.

Le lien ouvre le mauvais terminal

Sur macOS, démarrez claude dans votre terminal préféré une fois et le prochain lien profond l'utilisera. Sur Linux, définissez la variable d'environnement $TERMINAL sur le nom de commande de votre émulateur préféré. Sur Windows, l'ordre est fixe : installez Windows Terminal si vous voulez que les liens s'ouvrent là au lieu d'une fenêtre PowerShell ou cmd.exe.

En savoir plus

Ces pages couvrent les façons connexes de lancer ou d'étendre les sessions Claude Code :

• Skills : stockez une longue invite de runbook en tant que /skill dans le dépôt afin que le paramètre q du lien profond n'ait qu'à la nommer
• Mode non interactif : exécutez Claude à partir d'un script et capturez la sortie sans ouvrir de terminal