Sommaire de la documentation

// Documentation Singularity

Orchestration d'agents IA

Singularity transforme un ticket en mission autonome et observable : un agent lit la demande, travaille dans un espace isolé, rend compte de chaque étape, puis restitue un changement prêt à fusionner ou à relire.

Le principe : un ticket, un agent, un worktree

Le ticket est la mission de l'agent : son titre, sa description, ses pièces jointes et son contexte deviennent le cahier des charges de l'exécution. Lorsque l'isolation par worktree est activée, Singularity crée une copie Git dédiée sur une branche propre. L'agent peut ainsi lire, modifier, tester et committer sans perturber votre répertoire de travail.

À la fin, les commits sont replacés sur la branche de base par rebase. L'historique reste linéaire et plusieurs agents peuvent avancer en parallèle sans partager les mêmes fichiers de travail.

Lancer un agent

Vous pouvez démarrer une exécution depuis une carte du board ou depuis le détail du ticket. Sélectionnez le fournisseur d'IA et le modèle adaptés à la mission, puis lancez l'agent. Le fournisseur correspond au CLI installé et authentifié sur votre machine ; le modèle détermine les capacités et le coût de la session.

Le planificateur peut aussi prendre automatiquement le prochain ticket prêt, selon les dépendances, la priorité et la limite d'agents simultanés. Les tickets non prêts restent à leur place.

Suivre l'exécution

Le terminal de l'agent affiche son flux en direct : commandes, outils et résultats. Sur Mission Control, la puce d'activité de la carte résume la phase courante — lecture, écriture, tests, commit ou attente — sans devoir ouvrir le terminal.

La mention Projets touchés est alimentée pendant la mission. Elle indique immédiatement quels dépôts ont été lus ou modifiés par l'agent.

Mission Control avec plusieurs cartes et leurs puces d'activité
Mission Control donne une vue d'ensemble des agents actifs et de leur phase courante.

Interagir pendant la mission

Une question bloquante place le ticket en attente et affiche qu'une action de votre part est nécessaire. Répondez dans le détail du ticket : la réponse est transmise à la même session et l'agent reprend avec tout son contexte.

Vous pouvez également envoyer un message pendant une exécution, arrêter le processus si la direction n'est plus la bonne, puis redémarrer ou relancer le ticket. L'arrêt est explicite : il ne se confond pas avec un échec technique.

Détail d'un ticket Singularity avec son exécution et ses actions
Le détail du ticket rassemble le contexte, les échanges et les commandes de l'exécution.

Comprendre la fin d'une exécution

À la fin de sa mission, l'agent enregistre un compte rendu détaillé et une résolution courte visible sur la carte. Le statut distingue clairement les issues :

  • Done : le travail est terminé et validé par le flux choisi.
  • Failed : l'exécution s'est arrêtée sur une erreur ; elle peut être relancée.
  • Pending : l'exécution est en pause, par exemple en attente d'une réponse, d'enfants ou de la file de commits.
  • User action : une intervention qui ne peut pas être automatisée est assignée à une personne.

Fusion automatique ou revue

Le réglage de fusion automatique décide de la dernière étape. Lorsqu'il est activé, Singularity réintègre le worktree après la réussite de l'exécution. Lorsqu'il est désactivé, le résultat est parqué pour inspection : vous pouvez lire le compte rendu, examiner les changements et choisir de les approuver ou de demander une correction.

Consultez la revue de code des runs pour le parcours de validation complet.

La passerelle MCP

Chaque session dispose d'un serveur MCP local et temporaire, authentifié pour cette seule exécution. C'est le canal par lequel l'agent dialogue avec Singularity : il peut lire le ticket et ses dépendances, enregistrer les projets touchés, publier sa phase d'activité, poser une question, joindre un document ou créer un ticket de suivi.

La passerelle expire avec la session. L'agent ne reçoit donc pas un accès général et permanent à l'application.

Terminal d'un agent en cours dans Singularity
Le terminal restitue le flux réel du fournisseur et les échanges avec la passerelle de session.

Bac à sable

Le bac à sable optionnel entoure le processus de l'agent de restrictions système : Seatbelt sur macOS et Landlock sur Linux. Selon le fournisseur et la configuration du projet, il limite notamment les accès au système de fichiers et au réseau afin qu'une commande de l'agent reste dans le périmètre prévu.

Cette protection complète l'isolation Git du worktree : le worktree sépare les changements de code, tandis que le bac à sable contraint le processus qui les produit.

Reprise après incident

Les exécutions, tentatives et sorties de terminal sont enregistrées au fil de l'eau. Si l'application se ferme, Singularity vérifie au prochain démarrage quelles sessions lui appartenaient et si leur processus existe encore, sans interrompre les agents d'une autre instance.

Une session encore valide peut être rattachée ou reprise nativement lorsque le fournisseur le permet, notamment avec Claude. Sinon, le ticket est placé dans un état récupérable et explicite plutôt que d'être silencieusement considéré comme terminé.

Questions fréquentes

Puis-je fermer Singularity pendant qu'un agent travaille ?

Oui. Au redémarrage, Singularity rapproche les exécutions enregistrées des processus encore actifs. Une exécution interrompue est reprise lorsque le fournisseur le permet, ou placée dans un état explicite afin d'être relancée.

L'agent modifie-t-il directement ma branche ?

Avec les worktrees activés, non : chaque exécution travaille dans une copie Git isolée. Son commit revient ensuite sur la branche de base par rebase, automatiquement ou après votre revue selon le réglage choisi.