# Installer Rationale et connecter vos agents · Rationale

> Comment installer le client Rationale sur macOS et Linux, ce que rationale init met en place, comment Claude Code et Codex capturent les décisions, comment connecter Claude, ChatGPT et Cursor via MCP, et exactement ce qui quitte votre machine.

Source: https://rationalehq.com/fr/docs
Language: fr

Documentation

# Installer Rationale et connecter vos agents

Tout ce dont une équipe a besoin pour faire tourner Rationale, dans l'ordre où cela se passe : installer le client sur chaque ordinateur portable, se connecter, le laisser capturer, connecter les assistants qui parlent MCP, et savoir ce qui quitte vos machines. Écrit pour le client tel qu'il est livré aujourd'hui.

Mis à jour en octobre 2026 · client 0.9.0

Sur cette page

1.  [Comment les pièces s'assemblent](#overview)
2.  [Avant de commencer](#requirements)
3.  [Installer le client](#install)
4.  [Se connecter et configurer : rationale init](#init)
5.  [Ce qui se passe pendant que vous travaillez](#day)
6.  [Commandes](#commands)
7.  [Connecter Claude, ChatGPT, Cursor et d'autres assistants (MCP)](#mcp)
8.  [Connecter GitHub et Jira](#connectors)
9.  [Ce qui quitte votre machine, et ce qui ne la quitte jamais](#data)
10.  [Mises à jour, retour arrière, désinstallation](#updates)
11.  [Quand quelque chose ne va pas](#troubleshooting)

## Comment les pièces s'assemblent

Rationale a trois parties. Un **client** sur la machine de chaque personne : un seul binaire, sans runtime, qui écoute les sessions d'agent de la personne. L'**application**, sur app.rationalehq.com, où vivent les décisions, les tâches et les journaux d'audit, et où l'équipe se connecte. Et un **serveur MCP distant**, sur mcp.rationalehq.com, par lequel des assistants comme Claude, ChatGPT et Cursor lisent et enregistrent des décisions.

Le client extrait les décisions avec l'agent auquel la personne est déjà connectée (`claude -p` pour Claude Code, `codex exec` pour Codex), sur cette machine. Rationale reçoit les décisions extraites, de courtes citations et des métadonnées : identifiant de session, numéros de tour, dépôt, branche, heure. La transcription ne quitte jamais la machine, sauf vers le fournisseur de l'agent lui-même, comme elle l'a toujours fait.

## Avant de commencer

-   macOS (un binaire universel) ou Linux sur x86\_64 ou arm64. Windows n'est pas encore pris en charge : l'installateur le dit et s'arrête.
-   Claude Code ou Codex connecté sur la machine. Le client utilise cette CLI pour extraire les décisions, sur l'abonnement de la personne elle-même ; il n'a jamais besoin de sa propre clé d'API.
-   Un espace de travail Rationale. Nous sommes en accès anticipé : demandez l'accès et nous configurons l'espace de travail avec vous sous un jour ouvré.
-   Un projet dans l'espace de travail qui liste le remote git de chaque dépôt que vous voulez capturer. Le client route chaque session d'après ce remote ; un dépôt qu'aucun projet ne liste n'est jamais capturé.
-   `curl` ou `wget`, et `sha256sum` ou `shasum`, présents sur tout macOS et Linux.

## Installer le client

Une commande, sans sudo :

```
curl -fsSL https://rationalehq.com/install.sh | sh
```

L'installateur place un seul binaire dans `~/.local/bin/rationale`. Il télécharge à côté du binaire, vérifie la taille et le sha256 contre le manifeste de release, lance `rationale --version` et le renomme à sa place. Il ne modifie jamais les fichiers de votre shell : si `~/.local/bin` n'est pas dans votre PATH, il affiche la ligne à ajouter. Il ne vous connecte à rien et n'installe aucun hook ; c'est le rôle de `rationale init`, l'étape suivante.

Avec Homebrew, à la place :

```
brew tap rationalehq/tap https://github.com/jorgebasilio/homebrew-tap
brew install rationalehq/tap/rationale
```

La première installation fait confiance au TLS de l'hébergeur du fichier, comme tout `curl | sh`. Chaque mise à jour ultérieure est vérifiée par le client lui-même contre un manifeste de release signé (voir Mises à jour, retour arrière, désinstallation).

## Se connecter et configurer : rationale init

À lancer une fois par machine, dans un dépôt que votre espace de travail liste :

```
rationale init
```

1.  **Connexion.** Il ouvre le navigateur avec un code court (le device flow). Vous vous connectez à Rationale et la machine reçoit son propre token, conservé dans `~/.config/rationale/config.json` (mode 600). Une connexion par espace de travail ; `rationale login` en ajoute une autre.
2.  **Vérification du dépôt.** Il demande lequel de vos espaces de travail a un projet qui liste le remote git de ce dépôt. Exactement un : capturé là. Aucun : non capturé, et il le dit. Deux : non capturé, et `rationale status` nomme les deux. Il ne devine jamais.
3.  **Hooks.** Pour Claude Code, il écrit quatre entrées dans `~/.claude/settings.json` (une sauvegarde est conservée, vos propres entrées restent intactes) : `Stop`, `UserPromptSubmit`, `SessionStart` et `PostToolUse`. Pour Codex, il ajoute quatre entrées à `~/.codex/hooks.json` ; Codex n'exécute un hook qu'une fois que vous lui avez fait confiance (`/hooks` dans la CLI, ou Review hooks dans l'application), et `init` et `status` vous le rappellent tant que ce n'est pas fait.
4.  **Watcher.** Sur macOS un job launchd (`~/Library/LaunchAgents/com.rationalehq.client.watcher.plist`), sur Linux un timer utilisateur systemd (`rationale-watcher.timer`), toutes les minutes : captures, passations, synthèses et mises à jour. Sans session utilisateur systemd, `init` le signale, et les hooks capturent quand même chaque tour.

`rationale status` montre à tout moment les connexions, l'espace de travail de ce dépôt, les hooks, le watcher et la dernière session.

## Ce qui se passe pendant que vous travaillez

-   **Capture.** Quand une session se termine (le hook `Stop` de Claude Code, ou le watcher pour Codex), le client construit un delta compact des nouveaux tours, sans la sortie des outils ni le raisonnement, et demande à votre agent d'y repérer les décisions : question, choix, critères, ce qui a été écarté, quand la réexaminer, les fichiers et la tâche concernés, et les propres mots de la personne qui confirment, corrigent ou retirent une décision antérieure. Une extraction qui échoue est retentée plus tard et ne bloque jamais l'agent.
-   **Alertes avant la modification.** Quand l'agent lit ou s'apprête à modifier un fichier auquel une décision est ancrée, le hook demande ces décisions à Rationale dans un budget de deux secondes et les montre à l'agent avant la modification : qui a décidé, l'essentiel, et combien de commits ont touché le fichier depuis. Si le serveur est lent, l'agent reçoit l'essentiel depuis un index local. Une décision qui nomme une classe, une table ou une clé de ticket est recherchée dans le contenu du fichier, sur votre machine ; ce contenu ne la quitte jamais.
-   **Contexte pour une tâche.** Tapez le `#handle` d'une tâche dans un prompt et l'agent démarre avec ce qui a été décidé dessus, qui y travaille et les pull requests ouvertes.
-   **Notes au début de la session.** Vos notes pour le dépôt, l'espace de travail et le projet parviennent à l'agent quand une session démarre.
-   **Passations.** Une session avec des décisions qui reste silencieuse 30 minutes reçoit une passation écrite pour la personne qui reprendra la tâche : résumé, prochaines étapes, questions ouvertes.
-   **Jamais bloquant.** Un hook qui échoue se termine silencieusement et laisse l'agent continuer. Rien n'attend le réseau, sauf l'alerte, qui a son budget.

## Commandes

Commande

Ce qu'elle fait

`rationale init [--url URL]`

Se connecter (navigateur), vérifier ce dépôt, installer les hooks et le watcher

`rationale login [--url URL]`

Se connecter à un autre espace de travail, ou renouveler une connexion

`rationale status`

Connexions, espace de travail de ce dépôt, hooks, watcher, dernière session

`rationale anchors check PATH`

Quelles décisions alerteraient un agent sur ce fichier, leur essentiel, et de combien le fichier a bougé depuis

`rationale capture --task HANDLE`

Capturer maintenant, pour une tâche ; `--dry-run --print-delta` montre ce qui serait envoyé

`rationale record --title "..." < thread.txt`

Un fil collé ou des notes, passés par l'extracteur, enregistrés comme un seul tour

`rationale deploy production [--ref REF]`

Indiquer à Rationale ce qui est parti en production depuis cette machine : sha, branche, commits

`rationale digest`

Résumer les projets dont la synthèse est due, avec votre propre agent : état, sujets, où en sont les tâches

`rationale pause codex [--hours N]`

Suspendre un temps l'extraction avec votre Codex ; `rationale resume codex` la reprend. Les hooks continuent d'alerter.

`rationale update [--rollback]`

Vérifier la release signée maintenant et l'installer, ou remettre la précédente

`rationale uninstall`

Retirer les hooks et le watcher ; révoquez ensuite l'appareil dans l'application

## Connecter Claude, ChatGPT, Cursor et d'autres assistants (MCP)

Les assistants qui parlent le Model Context Protocol lisent les décisions de votre équipe et en enregistrent de nouvelles via le serveur distant à `https://mcp.rationalehq.com/mcp`. Il utilise OAuth 2.1 : collez l'URL, connectez-vous une fois dans le navigateur et autorisez vos espaces de travail. Chaque outil indique s'il lit ou écrit : `context_for`, `list_tasks`, `record_decision`, `record_handoff`, `record_note`, `pull_request_for` et quelques autres.

-   **Claude Code :** `claude mcp add --scope user --transport http rationale https://mcp.rationalehq.com/mcp`, puis la connexion dans le navigateur que Claude Code ouvre.
-   **Codex :** `codex mcp add rationale --url https://mcp.rationalehq.com/mcp`, puis `codex mcp login rationale`.
-   **Claude (claude.ai et l'application de bureau) :** Settings → Connectors → Add custom connector, avec l'URL ci-dessus. Connectez-vous quand Claude le demande.
-   **ChatGPT :** Settings → Connectors → Create, avec l'URL ci-dessus (les connecteurs personnalisés nécessitent un abonnement qui les autorise). Connectez-vous quand ChatGPT le demande.
-   **Cursor et les autres clients MCP :** ajoutez un serveur avec cette URL dans les réglages MCP du client (pour Cursor, `~/.cursor/mcp.json`) et connectez-vous quand il vous le demande.

Un projet peut fixer son espace de travail avec `?workspace=slug` dans l'URL. La page Get started de l'application affiche les mêmes commandes avec vos informations déjà renseignées.

## Connecter GitHub et Jira

Dans l'application, Settings → Connectors. GitHub s'installe comme GitHub App sur les organisations que vous choisissez ; Jira se connecte par OAuth à votre site Atlassian. Les deux sont propres à chaque membre : chaque personne ne voit dans Rationale que les dépôts, pull requests, tickets et projets que son propre compte peut voir.

Les pull requests, les relectures et les issues sont reliées aux décisions qui régissent les fichiers qu'elles modifient. Les tickets et les epics Jira deviennent des tâches, et les décisions suivent le ticket. Sans outil de suivi, les tâches vivent dans Rationale et les agents les ouvrent à la demande.

## Ce qui quitte votre machine, et ce qui ne la quitte jamais

Quitte la machine

Ne la quitte jamais

Les décisions extraites, avec de courtes citations des propres mots de la personne

La transcription de la session

Identifiant de session, numéros de tour, remote du dépôt, branche, commit, heure, et le coût équivalent de l'extraction

Les fichiers de votre dépôt : Rationale stocke des chemins, jamais le contenu

Les chemins des fichiers qu'un agent lit ou modifie, pour demander quelles décisions s'appliquent

Le contenu comparé aux identifiants d'une décision (lu localement, 512 Ko au plus)

Une passation et une synthèse de projet, écrites par votre agent

Les valeurs de secrets : refusées dans ce que les personnes et les agents écrivent, masquées dans les citations

L'extraction, les passations et les synthèses s'exécutent avec votre propre agent, sur votre propre abonnement : le coût reste de votre côté et visible, chaque capture porte son coût équivalent. Le client signale le résultat d'une mise à jour (ok, mauvaise signature, retour arrière) sous forme de code dans sa requête suivante, jamais dans un journal.

## Mises à jour, retour arrière, désinstallation

Le watcher, jamais un hook, vérifie le manifeste de release signé au plus toutes les six heures et remplace le binaire sur place, en conservant le précédent. Deux clés publiques minisign sont compilées dans chaque binaire : une clé de release qui signe chaque manifeste, et une clé de secours hors ligne qui sert uniquement à faire tourner la première. Un manifeste qu'aucune des deux clés n'a signé est refusé ; un manifeste rejoué aussi. Les installations Homebrew se contentent de signaler qu'une version plus récente existe.

```
rationale update
rationale update --rollback
```

Pour partir : `rationale uninstall` retire les hooks et le watcher ; révoquez ensuite l'appareil sur la page Devices de l'application, ce qui invalide son token. La configuration reste dans `~/.config/rationale/` et l'état dans `~/.local/state/rationale/` jusqu'à ce que vous les supprimiez.

## Quand quelque chose ne va pas

-   **`rationale: command not found` :** `~/.local/bin` n'est pas dans votre PATH ; l'installateur a affiché la ligne à ajouter au profil de votre shell.
-   **Les sessions ne sont pas capturées :** lancez `rationale status`. Le remote du dépôt doit être listé par exactement un projet dans un de vos espaces de travail ; deux espaces de travail qui le revendiquent arrêtent la capture jusqu'à ce que l'un des deux l'abandonne. Les hooks Codex ne capturent qu'une fois que vous leur avez fait confiance.
-   **Les alertes n'apparaissent pas :** le hook dispose d'un budget de deux secondes et abandonne silencieusement sur un réseau lent ; le suivant réessaie. `rationale anchors check PATH` montre ce qu'un hook dirait pour un fichier.
-   **Proxy d'entreprise :** le client utilise le magasin de certificats de votre plateforme ; un proxy avec son propre certificat racine fonctionne donc sans configuration.
-   **Tout le reste :** support@rationalehq.com, avec la sortie de `rationale status`. Elle ne contient ni transcription ni texte de décision.

Autre chose : [support@rationalehq.com](mailto:support@rationalehq.com)