Overstory : orchestrer plusieurs agents de code sur un meme repo avec des garde-fous concrets

https://github.com/jayminwest/overstory

📌 Overstory transforme une session de code classique en equipe multi-agents coordonnee dans un seul projet Git, avec worktrees isoles, supervision via tmux et messagerie SQLite pour garder un flux de travail lisible meme quand plusieurs agents avancent en parallele.

Quand un projet devient trop large pour un seul agent, le probleme n’est pas seulement la vitesse, c’est la coordination. Overstory repond a ce point precis: lancer plusieurs agents sur des taches distinctes, les isoler techniquement pour eviter les collisions de fichiers, puis remettre tout le travail dans la branche principale avec une logique de merge structuree. L’approche est orientee execution reelle, pas demo: on dispose d’une CLI complete pour initier le projet, ouvrir des sessions, suivre l’etat des agents, lire les messages internes, relancer un agent bloque et piloter la fusion finale.

Le coeur du systeme repose sur un trio simple: git worktree pour l’isolation de chaque agent, tmux pour gerer des sessions persistantes, et une couche SQLite pour la communication et le suivi d’evenements. Ce choix rend le comportement plus predicible qu’une orchestration basee sur des prompts libres uniquement. Chaque agent travaille dans son espace, ce qui limite les modifications concurrentes non maitrisees sur les memes fichiers. En pratique, cela simplifie les cycles “explorer -> implementer -> verifier -> merger” sans bloquer tout le monde sur une seule branche active.

Overstory est aussi pense pour rester compatible avec des environnements heterogenes. Le projet expose une interface runtime (AgentRuntime) qui permet de brancher differents CLIs d’agents: Claude Code, Pi, Codex, Gemini, Copilot, Sapling, OpenCode. Ce point est critique pour eviter l’enfermement: une equipe peut conserver ses habitudes et ses modeles preferes, tout en gardant la meme couche d’orchestration. Le runtime peut etre defini globalement dans la config ou force par agent pendant le lancement d’une tache.

Au demarrage, la sequence est directe. ov init cree la structure .overstory/ et initialise les composants necessaires. ov hooks install installe les hooks utiles pour proteger les operations sensibles et appliquer les contraintes d’execution. Ensuite, ov coordinator start demarre le coordinateur persistant qui repartit les taches et suit leur progression. Si besoin, ov sling lance des workers ciblant une capacite precise, comme builder, scout ou reviewer. Cette progression par etapes donne un chemin clair entre “je veux parallelliser” et “j’ai un flux operationnel stable”.

points cles

• ⚙️ Isolation propre: chaque agent tourne dans un worktree Git dedie pour limiter les conflits directs.
• 🧭 Orchestration durable: coordinateur persistant + supervision pour ne pas perdre le fil entre plusieurs runs.
• ✉️ Communication structuree: messagerie SQLite typée pour suivre les dispatchs, escalades et validations.
• 🔌 Runtime pluggable: support de plusieurs CLIs d’agents sans changer la logique d’orchestration.
• 📊 Observabilite complete: dashboard live, traces, logs, erreurs et metriques consultables en CLI.
• 🛡️ Garde-fous explicites: controles d’outils et recommandations fortes sur les risques des swarms.

Pour le quotidien, la valeur est immediate sur les taches qui se decomposent bien: refactor multi-modules, lot de bugs independants, generation de tests par domaine, migration de configuration, ou validation croisee avant merge. Au lieu de faire “une grosse passe” avec un agent unique, on peut repartir le travail par capacites et conserver une visibilite continue via ov status, ov dashboard, ov inspect, ov logs et ov costs. Cette instrumentation aide a decider vite: quel agent est bloque, lequel produit un signal utile, ou quand couper une branche devenue trop risquee.

Le volet fusion est un autre point fort. Overstory propose une file de merge FIFO avec resolution de conflits par paliers. Dans un contexte multi-agents, cette couche est essentielle: sans regles de merge explicites, la vitesse initiale se transforme vite en dette de synchronisation. Ici, l’outil impose un pipeline de reintegration qui garde une cadence exploitable quand plusieurs contributions arrivent presque en meme temps.

Le projet insiste aussi sur un aspect souvent minimise: les risques. L’auteur signale clairement que les swarms ne sont pas une solution universelle. Les erreurs peuvent se cumuler, les couts peuvent grimper, le debug devient plus dur, et les conflits de fusion sont frequents. Cette position rend l’outil plus credible: Overstory n’essaie pas de vendre une automatisation magique, il fournit des mecanismes concrets pour piloter une complexite reelle. Le bon usage consiste a choisir des lots de taches bien delimites, fixer des limites de profondeur, surveiller les sorties et interrompre rapidement les branches qui degradent la qualite.

Sur le plan technique, l’installation demande Bun (v1+), Git et tmux, plus au moins un runtime agent deja operationnel. C’est un prerequis raisonnable pour un environnement dev moderne. Le projet propose ensuite un set de commandes large: coordination, messaging, groupes de taches, monitoring, diagnostic (ov doctor), maintenance des worktrees et nettoyage. Cette couverture complete evite de bricoler des scripts satellites pour des operations basiques d’exploitation.

Cote confidentialite et maitrise des donnees, Overstory s’execute localement dans le repo et capitalise sur des composants standards du poste (CLI agent, tmux, sqlite locale). Cela aide a conserver le contexte de travail dans un perimetre technique connu. La confidentialite effective depend ensuite du runtime choisi et des modeles utilises, mais la couche d’orchestration reste orientee controle local, auditabilite des actions et traces consultables.

Pour un usage robuste, une strategie simple fonctionne bien: commencer avec peu d’agents, activer d’abord les roles lecture (scout, reviewer), limiter les merges automatiques, puis augmenter progressivement la parallelisation une fois les checks et les conventions d’equipe stabilises. Overstory donne les briques pour cette montee en charge sans perdre la lisibilite du projet.

Au final, Overstory est pertinent quand l’objectif n’est pas “lancer plus d’agents”, mais “orchestrer un travail multi-agents sans chaos operationnel”. Avec son architecture worktree + tmux + sqlite, ses adapters runtime et son outillage d’observabilite, il propose une base concrete pour industrialiser des workflows agentiques de code tout en gardant le controle technique.