Guide utilisateur

Installer et démarrer

Prérequis

Sur macOS ou Windows, utilisez Stream Deck 7.1 ou plus récent, avec macOS 13+ ou Windows 11+. Installez les harnais souhaités sur le même ordinateur, avec une version proposant les hooks nécessaires. Les sessions distantes, SSH et WSL ne sont pas raccordées automatiquement.

L’application Stream Deck doit rester en fonctionnement sur l’ordinateur. Avec un deck physique, l’application mobile est facultative. Pour utiliser un téléphone comme deck, configurez Stream Deck Mobile sur le même réseau Wi-Fi que l’ordinateur.

Premier lancement

1. Ouvrez le fichier com.sxnlabs.harness-deck.streamDeckPlugin fourni pour cette version et terminez son installation dans Stream Deck.
2. Sélectionnez votre appareil dans Stream Deck. Importez le profil fifteen-keys.streamDeckProfile pour un deck 15 touches, ou six-keys.streamDeckProfile pour le profil Mobile compact. Sélectionnez ensuite Harness Control · 15 keys ou Harness Control · 6 keys.
3. Cliquez sur une touche Harness Control dans l’éditeur Stream Deck pour afficher ses réglages, sous la grille de touches. La section Your agents permet de connecter les harnais.
4. Connectez Claude Code ou Codex en suivant le chapitre de connexion, puis démarrez une nouvelle session locale.
5. Cliquez sur Check again. Le statut Session received confirme qu’un événement de session est arrivé au plugin pendant son fonctionnement actuel.

Le statut Configured confirme la présence des réglages de connexion. La réception d’une session se vérifie séparément avec Session received. Une session déjà ouverte avant l’installation peut nécessiter un redémarrage pour charger ses hooks.

Connecter Claude Code et Codex

Claude Code

Dans Your agents, repérez la carte Claude Code. Vérifiez le dossier du profil par défaut, puis cliquez sur Connect. Démarrez une nouvelle session Claude Code avec votre configuration habituelle et vérifiez Session received.

Par défaut, le dossier est ~/.claude, ou le chemin absolu défini par CLAUDE_CONFIG_DIR dans l’environnement du plugin. Harness Control ajoute ses hooks au profil choisi et sauvegarde les réglages modifiés. Les hooks existants et les règles de permission sont conservés.

Plusieurs configurations Claude

Pour utiliser, par exemple, Perso et Manda :

1. Renommez le profil par défaut Perso, puis cliquez sur Save name.
2. Ouvrez Add Claude profile. Saisissez Manda et le chemin absolu d’un dossier de configuration existant, par exemple /Users/votre-nom/.claude-manda sur macOS. Le champ attend le chemin complet, sans ~.
3. Cliquez sur Add profile, puis sur Connect pour ce profil.
4. Relancez chaque session avec son dossier habituel. Sur macOS ou Linux, le second profil peut être lancé avec la commande ci-dessous si ce dossier existe.

CLAUDE_CONFIG_DIR="$HOME/.claude-manda" claude

Sur Windows, lancez le second profil dans PowerShell avec :

$env:CLAUDE_CONFIG_DIR = "$env:USERPROFILE\.claude-manda"
claude

Dans PowerShell, cette variable reste définie dans le terminal courant. Utilisez des fenêtres distinctes pour les deux profils.

Les deux profils apparaissent sur la ligne Claude, avec leur nom de profil et le début du nom de la session. Ils ont des demandes d’autorisation et des réglages de connexion distincts. Disconnect sur Manda déconnecte uniquement Manda. Harness Control laisse vos comptes et alias de terminal dans leurs réglages habituels.

Codex

Cliquez sur Connect dans la carte Codex. Dans Codex CLI, ouvrez /hooks, examinez les hooks Harness Control nouveaux ou modifiés et accordez-leur votre confiance. Démarrez ensuite une nouvelle session locale, puis vérifiez Session received. Codex exige cette revue avant d’exécuter ces hooks, y compris après certaines mises à jour. Documentation officielle des hooks Codex.

Les autorisations affichées dépendent du mode de permission de l’agent et de l’opération demandée. Pour Claude, un hook de permission intervient lorsque l’agent doit demander une décision concernant un outil. Référence Claude Code.

Ouvrir une session dans le terminal

Sélectionnez la session sur le deck, puis ouvrez Selected session dans les réglages d’une touche. Renseignez Exact terminal window title avec le titre complet et unique de sa fenêtre ; la valeur est enregistrée quand le champ est modifié.

Sur macOS, cette commande cible Ghostty. Au premier usage, suivez les demandes macOS pour autoriser le contrôle de fenêtres ; si l’accès est refusé, vérifiez Réglages Système > Confidentialité et sécurité > Accessibilité. Une fenêtre portant ce titre doit être ouverte. La commande ne sélectionne pas un onglet en arrière-plan. Pour une session Codex desktop sans origine terminal, Open utilise son lien de session dans Codex.

Utiliser les touches

Profil 15 touches

Les deux premières lignes affichent dix sessions : Claude Code puis Codex par défaut. Sur macOS et Windows, une app de harnais reconnue occupe les deux lignes. Un terminal partagé entre plusieurs harnais conserve les deux lignes configurées.

Un appui sur une session la sélectionne et l’ouvre si son connecteur le permet. Les commandes affichent son nom, son harnais et son profil Claude. Previous et Next parcourent les sessions et les pages sans ouvrir ; Archive archive la session sélectionnée dans un harnais pris en charge, puis la retire du Deck.

Les sessions récentes apparaissent en premier. Une nouvelle session peut déplacer des touches, mais une autre demande ne change pas votre sélection. Renommer une session ne la fait pas remonter.

Comprendre l’état affiché

Une touche en attente pulse doucement sur tout son fond, par cycle de trois secondes ; son texte reste stable. Les questions et choix de plan se traitent dans le harnais. Approve et Deny répondent aux autorisations d’outils prises en charge.

Approuver ou refuser

Sélectionnez la session en APPROVAL. Dans Selected session, consultez l’outil et les paramètres demandés, puis appuyez sur Approve ou Deny. La décision porte sur la demande sélectionnée, une seule fois, et ne crée pas de permission permanente.

Les boutons sont grisés en l’absence de demande. Une demande expirée, terminée ou répondue ailleurs ne peut plus être validée depuis son ancienne touche. Si le deck ou le plugin devient indisponible, Claude, Codex et Cursor reprennent leur traitement habituel des permissions ; aucune approbation automatique n’est accordée par Harness Control.

Archiver et restaurer une session

Sélectionnez une session Codex ou OpenCode, puis appuyez sur Archive. Le plugin demande son archivage au harnais et attend sa confirmation avant de la retirer des touches. Si la commande échoue, la session reste visible. Son historique est conservé dans les archives du harnais.

Pour Codex, installez un CLI proposant codex archive et codex unarchive ; le connecteur a été vérifié avec la version 0.161.0. Il utilise l’identifiant exact de la session et son dossier de configuration. OpenCode utilise son API locale, vérifiée avec 1.18.35, sur le serveur et le projet connectés.

Dans les réglages d’une touche, ouvrez Archived sessions puis cliquez sur Restore. Cette commande restaure aussi la session dans son harnais. Gardez le même dossier Codex ou reconnectez le serveur et le projet OpenCode d’origine. Si la session est fermée, reprenez-la dans le harnais après restauration. L’archivage ne transmet aucune décision Approve/Deny.

Pour Claude Code dans le terminal, Pi et Cursor, l’archivage natif n’est pas intégré dans cette version. La touche reste grisée et affiche UNAVAILABLE. Les profils Claude Perso et Manda conservent chacun leurs sessions. L’archivage documenté pour Claude Code cloud se fait depuis sa barre latérale ; il ne concerne pas automatiquement une session locale dans le terminal. Documentation Claude Code cloud.

Si vous utilisez un ancien profil 15 touches, remplacez sa touche Open par l’action Archive session depuis la bibliothèque Stream Deck. Les touches de session conservent l’ouverture directe.

Apparence et profil Mobile

Les sessions ont un fond uni par harnais, sans logo, et un grand titre sur quatre lignes au maximum. Le profil Claude accompagne l’état. Dans Deck appearance and layout, réglez les commandes (Dark background / Solid color background) et les harnais des lignes (First session row / Second session row).

Le profil Mobile compact propose Open, Approve, Deny, Stop, Previous et Next. Dans Codex, Pi et Cursor, STOP IN APP indique une interruption manuelle. Le profil 15 touches fourni ne contient pas de touche Stop.

Connecter OpenCode, Pi et Cursor

OpenCode

Dans la carte OpenCode, cliquez sur Set up server. Raccordez le plugin au serveur local utilisé par votre session OpenCode. Pour démarrer un nouveau terminal avec une adresse connue :

opencode --hostname 127.0.0.1 --port 4096

Dans OpenCode connection, cochez Enable OpenCode, saisissez http://127.0.0.1:4096, choisissez OpenCode terminal, puis cliquez sur Save connection. Si votre serveur utilise un mot de passe, renseignez ses identifiants dans cette section. Le statut Connected peut apparaître même si aucun projet ou aucune session n’est encore affiché.

Un serveur lancé séparément avec opencode serve représente une autre instance : utilisez l’adresse de celui qui accompagne votre terminal. Le champ Project directory (optional) permet de cibler un projet. Terminal app renseigne l’application de terminal pour le changement de ligne ; la mise au premier plan demande aussi un titre exact de fenêtre. Documentation du serveur OpenCode.

Open sélectionne la session via OpenCode lorsque le terminal est attaché à ce serveur. Avec Desktop app, ouvrez la session manuellement dans OpenCode. Approve/Deny répondent à une demande individuelle ; Stop utilise le serveur OpenCode.

Pi

Cliquez sur Prepare Pi, puis sur Copy command. Exécutez la commande affichée dans le terminal indiqué. Sur Windows, utilisez PowerShell, comme le précise l’interface. Cette commande lance Pi avec l’extension Harness Control pour cette session.

L’extension ajoute une confirmation individuelle pour les commandes shell, les écritures et les outils personnalisés ou MCP. Les outils de lecture intégrés passent directement. Si le deck ne répond pas, une session Pi interactive peut demander une confirmation dans Pi ; sans interface interactive, l’outil est bloqué. Stop se fait dans Pi.

Pour lancer une session sans cette connexion, démarrez Pi sans l’option d’extension Harness Control. Aucune extension globale n’est installée par ce bouton.

Cursor

Cliquez sur Connect, puis démarrez une nouvelle conversation locale dans Cursor. Les demandes de commandes shell et d’outils MCP peuvent être approuvées ou refusées depuis le deck. Les modifications de fichiers alimentent l’état de la session ; leurs autorisations ne sont pas accordées par ce connecteur. L’ouverture des conversations et Stop se font dans Cursor.

Commandes disponibles

L’ouverture et l’interruption des fenêtres dépendent aussi du système utilisé, comme indiqué dans le chapitre compatibilité.

Résoudre un problème

Cliquez sur une touche Harness Control dans l’éditeur, puis sur Check again. Lisez le statut et le message de la carte concernée, ou du profil Claude précis.

Aucune session n’apparaît

Vérifiez que le profil Stream Deck sélectionné appartient à Harness Control, que le plugin est installé et que Stream Deck fonctionne. Relancez l’agent après connexion. Pour Claude, contrôlez le dossier utilisé au lancement ; pour Codex, la confiance accordée aux hooks ; pour Pi, la commande avec extension ; pour OpenCode, le serveur et le projet ciblés.

Les sessions Claude, Codex et Cursor apparaissent à partir de leurs événements locaux. L’historique complet de ces applications n’est pas ajouté au deck. Après un redémarrage du plugin, reprenez l’activité des sessions ou démarrez-en de nouvelles.

Une touche clignote, mais Approve reste grisé

La session peut attendre une question ou un autre choix. Ouvrez le harnais pour lire la demande. Approve/Deny deviennent actifs lorsqu’une demande d’autorisation d’outil prise en charge est en attente. Les opérations déjà autorisées par vos règles peuvent s’exécuter sans faire apparaître de demande sur le deck.

Une touche affiche un point d’exclamation

Le triangle indique qu’une action n’a pas pu être exécutée. Cliquez sur cette touche dans l’éditeur Stream Deck pour lire le message du plugin. Si la touche concernée est Open, contrôlez le titre de fenêtre et les autorisations décrits ci-dessous.

Open ne ramène pas la bonne fenêtre

Vérifiez Exact terminal window title pour la session sélectionnée. Le titre doit correspondre à une seule fenêtre ouverte ; deux fenêtres identiques ou un titre modifié empêchent le ciblage. Sur macOS, utilisez Ghostty et vérifiez l’autorisation Accessibilité. Sur Windows, le système peut refuser la mise au premier plan. Un onglet en arrière-plan doit être sélectionné manuellement.

Le nom affiché est celui du projet

Le plugin affiche le projet lorsqu’aucun nom de session exploitable n’est disponible. Après un renommage dans le harnais, attendez quelques secondes. Le chemin de la session et le nom utilisé par le plugin se consultent dans Selected session.

Demander de l’aide

Contactez nathan@sxnlabs.com avec le système, les versions de Stream Deck, Harness Control et du harnais, le modèle du deck, le statut affiché et les étapes pour reproduire le problème. Une capture des statuts suffit souvent ; masquez les noms de projets, chemins et paramètres d’outils confidentiels.

Compatibilité, mises à jour et données

macOS, Windows et Linux

Sur Linux, suivez les instructions OpenDeck, notamment les règles d’accès au périphérique et l’installation de Node sur l’hôte avec Flatpak. Importez le fichier harness-control-0.9.5.0-linux-opendeck.streamDeckPlugin, ajoutez les actions Harness Control et connectez vos agents dans leurs réglages. Ce package se destine à OpenDeck.

Mettre à jour

Installez la nouvelle version du plugin, puis ouvrez les réglages d’une touche. Si une carte indique Update needed, mettez à jour sa connexion. Examinez les hooks Codex modifiés avec /hooks et relancez les sessions concernées.

Conservez vos profils Stream Deck et vérifiez les lignes, l’apparence et les titres exacts après la mise à jour. Stream Deck propose une sauvegarde des profils. Une demande en attente avant un redémarrage doit être traitée dans le harnais ; le plugin ne la réapprouve pas à son retour.

Déconnecter ou désinstaller

Pour Claude Code, cliquez sur Disconnect à côté du profil concerné. Pour Codex ou Cursor, ouvrez Details et cliquez sur Disconnect. Les hooks Harness Control du connecteur sont retirés, tandis que les autres réglages sont conservés. Relancez les sessions pour charger cette modification. Un profil Claude ajouté peut ensuite être retiré avec Remove ; son dossier de configuration reste présent.

Pour OpenCode, décochez Enable OpenCode puis cliquez sur Save connection. Pour Pi, relancez sans l’extension. Déconnectez les harnais souhaités avant de désinstaller le plugin dans Stream Deck.

Données utilisées

La liaison entre Harness Control et les sessions est locale. Le plugin utilise leurs noms, projets, états et demandes d’outils pour afficher les touches et la demande sélectionnée. Les noms sont recherchés dans les métadonnées locales des sessions déjà reçues ; aucun historique complet de conversations n’est importé.

Les comptes Claude et OpenAI restent dans leurs applications. Les éventuels identifiants de serveur OpenCode sont enregistrés dans les réglages du plugin sur cet ordinateur. Vos harnais continuent d’utiliser leurs services habituels selon leur propre configuration.

Revenir en haut ↑