// 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.

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.

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.

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.