Guide de AGY Sessions

1Installation

Seul prérequis : Antigravity CLI installé (la commande agy fonctionne dans un terminal). Node.js n'est pas nécessaire pour utiliser l'application de bureau.

L'application n'est pas encore signée par un certificat éditeur, chaque système prévient donc au premier lancement :

• Windows : « Windows a protégé votre ordinateur » → Informations complémentaires → Exécuter quand même.
• macOS : au premier lancement, macOS bloque l'app (« impossible de vérifier le développeur »). Ouvre Réglages Système › Confidentialité et sécurité, descends jusqu'au message sur AGY Sessions et clique Ouvrir quand même (puis confirme). Sur les macOS récents, « clic droit › Ouvrir » ne suffit plus. Autre possibilité, dans le Terminal : xattr -cr "/Applications/AGY Sessions.app".

Ensuite, les nouvelles versions s'installent toutes seules sous Windows (§ 17).

2Premiers pas

1. Lance AGY Sessions. Au premier lancement, un assistant vérifie que agy et git sont installés et propose de créer ta première session.
2. + Nouvelle (Ctrl+Alt+N ou ⌥+⌃+N) : choisis un dossier de travail (Parcourir…), éventuellement un nom et un groupe, le modèle (gemini-2.5-pro, claude-3-7-sonnet, etc.), le niveau de réflexion (effort), puis Lancer.
3. La session démarre : c'est un vrai Antigravity CLI, avec tes règles, tes skills, tes hooks personnalisés, tes serveurs MCP et tes slash commands (/goal, /plan, /schedule, /browser, etc.). Tu tapes comme dans un terminal.
4. Crée d'autres sessions de la même façon : elles apparaissent dans la barre latérale et tournent toutes en même temps.

Tu peux fermer la fenêtre à tout moment : les sessions continuent en arrière-plan et reviennent même après un redémarrage de l'ordinateur.

3L'écran principal

┌─ barre latérale ──────┬─ barre de la session active ────────────────────────────────────────┐
│ + Nouvelle            │ ● nom ✎  ⎇ branche  dossier  état   ▢◫⊟⊞  ± Modifications  ↗ Ouvrir │
│ Rechercher…   Ctrl+K  │                                    Joindre  Relancer  ⋯  Fermer     │
│ ─ ÉPINGLÉES ─     1   ├──────────────────────────────────────────────────┬──────────────────┤
│ ● session A           │                                                  │ panneau latéral  │
│ ─ PROJET X ─      2   │   terminal de la session (ou 2 / 4 panneaux)     │  Modifications   │
│ ● session B           │                                                  │  Chronologie     │
│ ● session C           │                                                  │  Consommation    │
│ ─ SANS GROUPE ─   1   │                                                  │                  │
│ ● session D (verrou)  │                                                  │                  │
│ Dans un terminal (2)  │                                                  │                  │
│ Historique   ⚙   ⇤    │                                                  │                  │
└───────────────────────┴──────────────────────────────────────────────────┴──────────────────┘

• Barre latérale : tes sessions, rangées par groupe, avec leur état en direct. En bas : l'historique des conversations, les réglages (⚙) et le mode compact (⇤).
• Barre de la session active : nom (✎ renommer), branche si c'est un worktree, dossier, état ; à droite la disposition (1, 2 ou 4 panneaux), le panneau Modifications, « Ouvrir dans… », joindre un fichier (📎), relancer, le menu ⋯ (toutes les actions de la session) et Fermer.
• Clic droit partout : menu adapté (session, terminal, champ de saisie, historique, icône de la zone de notification).

États d'une session

Après Ctrl+C ou Échap pendant une réponse, la session repasse à « prêt (interrompu) ». Une session rouge le reste tant qu'Antigravity attend vraiment : l'afficher ne suffit pas, il faut lui répondre.

L'état vient directement des hooks du cycle de vie Antigravity (PreInvocation, PreToolUse, Stop configurés automatiquement dans ~/.gemini/config/hooks.json) : il est exact même fenêtre fermée.

4Les sessions

Persistance : chaque session ouverte (dossier, nom, modèle, groupe, ordre, identifiant de conversation) est mémorisée. Après un redémarrage de l'ordinateur ou de l'app, toutes celles qui tournaient sont relancées dans leur conversation. Seules celles que tu as arrêtées ou fermées restent arrêtées.

5Ranger : groupes, épinglage, couleurs

Un groupe est une étiquette libre qui sert à ranger tes sessions par projet dans la barre latérale — par exemple « Backend », « Frontend », « Client X », « Expérimentations ». Il n'a aucun effet sur le fonctionnement des sessions : c'est de l'organisation visuelle.

• Définir le groupe : champ Groupe dans « Nouvelle session » (les groupes existants sont proposés), ou plus tard ⋯ › Groupe… (taper - pour retirer la session de son groupe).
• Affichage : chaque groupe a un en-tête (nom + nombre de sessions) ; clic sur l'en-tête = replier / déplier. Les sessions sans groupe sont sous « Sans groupe ».
• Épingler (⋯ › Épingler en haut) : la session passe dans « Épinglées », tout en haut, quel que soit son groupe.
• Couleur : liseré à gauche de la session pour la repérer d'un coup d'œil.
• Un modèle de session peut fixer le groupe (§ 12).

6Vue partagée

Pour suivre plusieurs sessions en même temps : boutons de disposition dans la barre (▢ une, ◫ deux colonnes, ⊟ deux lignes, ⊞ grille 2×2) ou palette.

• Placer une session : glisse-la depuis la barre latérale sur un panneau, ou clique-la (elle va dans le panneau actif, surligné en cyan/indigo).
• Changer de panneau : clic dans le panneau ou Ctrl+Alt+←/→ ; ✕ en haut d'un panneau le vide.
• Chaque terminal garde sa propre taille ; la disposition est mémorisée.
• Mode focus (Ctrl+Alt+F) : masque la barre latérale.

7Worktrees git : plusieurs AGY sur le même dépôt

Deux sessions qui modifient le même dépôt au même moment se marchent dessus. Un worktree git donne à une session son propre dossier et sa propre branche, à côté du dépôt principal, sans y toucher.

1. « Nouvelle session » dans un dépôt git → cocher Travailler dans un worktree git dédié. Une branche est proposée (asm/<nom>), modifiable.
2. La session travaille dans <dépôt>.worktrees/<branche> ; son badge ⎇ branche apparaît dans la liste et la barre.
3. Travail prêt : panneau Modifications → commit, puis Fusionner dans <branche de base>.
4. En fermant la session : garder le worktree (y revenir plus tard), fusionner puis supprimer, ou supprimer (abandonner la branche).

La fusion est refusée s'il reste des modifications non commitées, si le dépôt principal n'est pas sur la branche de base, ou en cas de conflit (la fusion est alors annulée proprement).

8Panneau Modifications, Chronologie, Consommation

Bouton ± Modifications (Ctrl+Alt+G) ou ⋯ : panneau latéral à trois onglets pour la session active.

• Modifications : fichiers modifiés dans le dossier de la session (git) avec leur état (M modifié, N nouveau, S supprimé). Clic = diff coloré ; ↺ = annuler un fichier ; commit avec « Proposer un message » et « Committer tout ». Rafraîchi quand Antigravity a fini un tour.
• Chronologie : les actions d'Antigravity (📖 lecture de fichier, ✏️ écriture de code, ▶ commande terminal, 🔎 recherche web ou de code…) avec l'heure exacte.
• Consommation : tokens d'entrée / sortie et coût estimé de la session, puis de toutes les sessions sur 5 h, aujourd'hui et 7 jours ; graphique par jour ; sessions les plus coûteuses. Estimation calculée à partir des transcripts d'Antigravity.

Exporter une conversation : ⋯ › Exporter → Markdown (fichier ou presse-papiers) ou impression / PDF.

9Historique et sessions ouvertes dans un terminal

• Historique (🕘, Ctrl+Alt+H) : toutes tes conversations Antigravity de cet ordinateur (titre, dossier, branche, dernier message, transcript complet), filtrables. Clic = reprendre la conversation dans une nouvelle session, dans son dossier. Clic droit : renommer, copier le chemin ou l'identifiant.
• Dans un terminal (bas de la barre latérale) : les sessions agy lancées dans des terminaux externes apparaissent toutes seules grâce aux hooks. Clic → Déplacer (la session s'arrête dans le terminal et reprend ici, même conversation) ou Copier (le terminal continue, une copie s'ouvre ici). Tout ramener les déplace toutes.

10Images et fichiers

Comme dans un terminal natif, Antigravity reçoit images et fichiers :

• glisser-déposer un fichier sur le terminal ;
• coller une capture d'écran (Ctrl+V / ⌘+V) ;
• bouton 📎, ou clic droit › Joindre un fichier… / Coller.

Le fichier est copié dans un dossier temporaire et son chemin collé dans ta ligne de saisie : Antigravity reçoit le lien direct vers le fichier ou l'image et l'intègre dans le tour suivant. Les copies sont effacées automatiquement après 7 jours.

11Palette, recherche, prompts, file d'attente, envoi groupé

• Palette de commandes (Ctrl/⌘+K) : quelques lettres pour aller à une session, reprendre une conversation, lancer un modèle, insérer un prompt ou exécuter une action (disposition, thème, réglages, diagnostic, verrouillage…). Les actions récentes remontent en tête.
• Rechercher dans les sessions (Ctrl/⌘+Maj+F) : un texte dans le contenu de tous les terminaux ouverts ; clic = y aller.
• Bibliothèque de prompts (⋯ › Insérer un prompt…, palette, Réglages › Prompts) : tes demandes réutilisables. Elle démarre avec 8 prompts prêts à l'emploi (relire les modifications, écrire les tests, expliquer du code, préparer un commit, corriger un bug, proposer un plan avec /plan, documenter, résumer), modifiables et supprimables ; + Nouveau pour ajouter les tiens. Insérer les place dans la ligne de saisie ; Envoyer les soumet directement. Variables : {dossier}, {branche}, {nom}, {selection} (texte sélectionné dans le terminal).
• File d'attente (⋯ › File d'attente…, Ctrl+Alt+Q) : des prompts envoyés un par un, automatiquement, chaque fois qu'Antigravity a fini le précédent — « implémente », puis « ajoute les tests », puis « relis ». Le badge ⏳ indique le nombre en attente.
• Envoi groupé (Ctrl+Alt+B) : le même prompt à plusieurs sessions cochées, tout de suite ou en file d'attente si elles travaillent.

12Modèles de session

Un modèle mémorise une session type : dossier, nom, groupe, modèle d'IA, effort, worktree, arguments et premier prompt (envoyé dès que la session est prête).

• Créer : sur une session existante, ⋯ ou clic droit › Enregistrer comme modèle… (reprend son dossier, son groupe, son modèle et ses paramètres) ; ou remplis « Nouvelle session » puis Enregistrer comme modèle.
• Utiliser : liste Modèle de session en haut de « Nouvelle session », ou palette › « Lancer le modèle : … ».
• Gérer : Réglages › Modèles de session (lancer, renommer, supprimer).

13Verrouiller une session par mot de passe

Pour masquer une session sensible (écran partagé, démonstration en direct, poste laissé ouvert) : ⋯ ou clic droit › Verrouiller par mot de passe… (Ctrl+Alt+L), avec un indice facultatif.

• La session continue de tourner, mais son contenu est masqué et la saisie bloquée : un écran 🔒 demande le mot de passe. Dans la liste, 🔒 = verrouillée, 🔓 = déverrouillée dans cette fenêtre.
• Le verrou est appliqué par le serveur : une fenêtre non déverrouillée ne reçoit ni l'affichage de la session ni son historique, et les actions sensibles (modifications, export, chronologie, consommation, file d'attente, fermeture) sont refusées ; son titre est masqué dans l'Historique.
• Déverrouiller ne vaut que pour la fenêtre où tu as tapé le mot de passe. Le verrou revient quand la fenêtre est réduite ou masquée, après une inactivité (Réglages › Sécurité), au redémarrage de l'app, ou tout de suite avec ⋯ › Verrouiller maintenant.
• ⋯ › Changer le mot de passe… / Retirer le mot de passe…
• Mot de passe haché (scrypt), tentatives protégées. Il ne peut pas être récupéré : si tu l'oublies, ferme la session (la conversation reste intacte dans les fichiers d'Antigravity).
• Limite : le verrou protège ce qu'affiche l'application ; les conversations enregistrées par Antigravity (~/.gemini/antigravity-cli/brain/) restent des fichiers locaux sur ton disque.

14Notifications, zone de notification, arrière-plan

• Notifications système quand une session attend ta réponse ou a fini (seulement si tu ne la regardes pas), avec un son au choix. Ne pas déranger coupe tout ; ⋯ › Couper les alertes le fait pour une seule session.
• Rappels si une session attend depuis X minutes ou travaille depuis plus de Y minutes (Réglages › Notifications).
• Pastille sur l'icône de l'app (Dock / barre des tâches) avec le nombre de sessions en attente. Sur macOS, notification système et point rouge sur l'icône du Dock.
• Zone de notification (Windows, près de l'horloge) / barre de menus (macOS) : réduire ou fermer la fenêtre l'y envoie, les sessions continuent. Clic sur l'icône = afficher / masquer ; clic droit = la liste des sessions et leur état (🟠 travaille, 🔴 attend, 🟢 prête ; clic pour y aller), nouvelle session, historique, réglages, lancer au démarrage, redémarrer le serveur, quitter. Un point rouge sur l'icône signale une session qui t'attend.
• Quitter : « Quitter (les sessions continuent) » ferme l'app ; « Quitter et arrêter toutes les sessions » arrête aussi le serveur (elles reviendront au prochain lancement).
• Lancement au démarrage de l'ordinateur : configurable et géré par LaunchAgent sur macOS et le Planificateur de tâches sur Windows.

15Thème clair / sombre, langue

• Thème : Système (par défaut) suit automatiquement le mode clair ou sombre de Windows / macOS, y compris quand il change en cours de journée ; ou forcer Clair / Sombre (Réglages › Général, ou palette › « Thème »). Le terminal adapte sa palette de couleurs au thème sélectionné.
• Langue : français ou anglais, automatiquement selon la langue du système, ou sélectionnée manuellement dans Réglages › Général.

16Réglages

⚙ en bas de la barre latérale, ou Ctrl/⌘+,.

17Mises à jour

• Windows : l'app vérifie les nouvelles versions, les télécharge en arrière-plan et affiche un bandeau Redémarrer pour mettre à jour. Le serveur est relancé avec le nouveau code et tes sessions reviennent toutes seules.
• macOS : l'app te prévient lorsqu'une mise à jour est disponible et ouvre la page de téléchargement de la version correspondante.
• Réglages › À propos › Rechercher des mises à jour pour vérifier immédiatement.
• Bandeau jaune « le serveur tourne une ancienne version » : clique Redémarrer le serveur pour recharger la dernière version du code sans perdre tes sessions.

18Raccourcis clavier

Sur Mac, Ctrl+Alt correspond aux touches ⌃+⌥ (Control+Option). Dans le terminal :

• Windows : Ctrl+C avec sélection copie, Ctrl+V colle, Ctrl++/−/0 zoome.
• macOS : ⌘+C/V/+/−/0 ; Ctrl+C envoie l'interruption à Antigravity.

19Données, sécurité, confidentialité

• Tout reste sur ta machine. Le serveur de l'application écoute exclusivement sur 127.0.0.1 (inaccessible depuis le réseau extérieur), exige un jeton d'accès aléatoire et valide l'en-tête Host. Aucune télémétrie ni pistage : seules tes sessions agy communiquent avec leurs API habituelles. Politique de confidentialité.
• Fenêtre isolée : bac à sable Electron, aucun accès Node.js direct depuis le moteur de rendu, navigation restreinte au serveur local, liens externes ouverts dans ton navigateur par défaut, permissions strictes et Content Security Policy (CSP).
• Données de l'app : %APPDATA%\agy-sessions (Windows), ~/Library/Application Support/agy-sessions (macOS) — sessions ouvertes, réglages, modèles, bibliothèque de prompts, jeton et journaux. Désinstaller l'app ne supprime pas tes données personnelles.
• Conversations : ce sont les conversations Antigravity natives stockées dans ~/.gemini/antigravity-cli/brain/ ; AGY Sessions les lit pour l'historique et la reprise, sans jamais altérer le contenu des transcripts.

20Dépannage

21Ligne de commande asm (sans l'application)

Pour utiliser AGY Sessions directement dans ton navigateur préféré, sans l'application Electron de bureau (prérequis : Node.js 18+) :

git clone https://github.com/vantaflow/agy-sessions-manager.git ~/agy-sessions-manager
cd ~/agy-sessions-manager
npm ci && npm install -g .   # installe la commande globale « asm » (et son alias « agys »)
asm install                  # configure le démarrage automatique + lanceur système
asm                          # démarre et ouvre l'interface dans ton navigateur

Autres commandes disponibles :

• asm status : affiche l'état d'exécution et l'URL du serveur (http://127.0.0.1:7892/).
• asm stop : arrête le serveur (toutes les sessions actives seront restaurées au prochain lancement).
• asm restart : redémarre le serveur et relance les sessions.
• asm log : affiche les 60 dernières lignes du journal du serveur.
• asm where : affiche les chemins du code source, du dossier de données et de l'exécutable Node.js.
• asm uninstall : supprime le LaunchAgent / la tâche planifiée et le raccourci applicatif.

Variables d'environnement :

• ASM_PORT (défaut 7892 ; spécifier un autre port permet d'isoler des environnements distincts).
• ASM_DATA : dossier de stockage des données de session.
• ASM_AGY : chemin explicite vers l'exécutable agy.

22Développement

npm ci
npm test            # tests d'intégration du serveur (mock agy, profil temporaire isolé)
npm run test:app    # tests de l'application Electron avec Playwright
npm run app         # lancer l'application en mode développement
npm run dist:win    # générer l'installeur Windows (dist/AGY-Sessions-Setup-x.y.z.exe)
npm run dist:mac    # générer les installeurs macOS (dist/AGY-Sessions-x.y.z-arm64.dmg et x64.dmg)

Architecture du projet :

• server.js : serveur HTTP et WebSocket local, gestion des processus pseudo-terminaux (node-pty) pour chaque session, injection et surveillance des hooks d'état du cycle de vie agy.
• hook.js : script de hook notifiant le serveur des événements PreInvocation, PreToolUse et Stop.
• lib/ : modules modulaires (gestion des worktrees git, consommation de tokens, verrous par mot de passe, réglages utilisateurs, file d'attente de prompts, outils système).
• public/ : interface web monopage (SPA), moteur de rendu de terminal xterm.js avec WebGL, gestion i18n FR/EN.
• electron/ : application de bureau, intégration système (icône barre des tâches / barre des menus, raccourcis globaux, fenêtrage natif).