TheBotCompany : démarrer — une équipe d’IA sans intervention humaine

30 minutes pour maîtriser｜Collaboration autonome à trois rôles｜Garde-fous multi-Provider｜Automatisation de bout en bout, des besoins jusqu’au PR

---

Présentation du projet

TheBotCompany est une plateforme d’équipe de développement IA qui vous permet de « lâcher prise » pour de bon. Son idée centrale est très simple : au lieu que ce soit vous, seul, en train de discuter avec une IA pour coder, vous constituez une équipe composée de plusieurs agents IA — l’un planifie, un autre développe, un autre vérifie. Ils échangent et se répartissent eux-mêmes les tâches, gèrent l’avancement de façon autonome. Vous n’avez qu’à intervenir uniquement lorsqu’ils rencontrent un cas où un vrai jugement humain est réellement nécessaire.

Dans l’équipe, trois rôles de gestion sont fixes : Athena fait la planification stratégique, en définissant les jalons et le budget de cycles ; Ares mène l’exécution, en découpant chaque jalon en tâches concrètes pour les agents ouvriers ; Apollo assure la validation, en examinant rigoureusement les livrables d’Ares et en les rejetant s’ils ne sont pas conformes. Cette boucle ne nécessite pas que vous la surveilliez : le Dashboard affiche en temps réel ce que fait chaque agent, combien cela coûte et quels problèmes sont apparus.

---

Profil des lecteurs visés

Cet article s’adresse aux développeurs suivants :

• Vous avez une expérience de développement et souhaitez confier les tâches de codage répétitives à une équipe d’agents IA, pour vous concentrer sur la décision et l’architecture
• Vous vous intéressez aux notions de collaboration Multi-Agent et d’équipes auto-organisées, et vous cherchez des cas concrets
• Vous utilisez déjà un seul agent pour vous assister dans le développement, mais vous voulez passer à plusieurs agents en parallèle pour traiter plusieurs directions

Si ce que vous cherchez, c’est un outil où l’on peut « tout installer puis se reposer complètement », il faut d’abord ajuster les attentes : TheBotCompany réduit fortement les interventions humaines, mais ne les supprime pas totalement.

---

Dépendances essentielles et environnement

---

Arborescence complète du projet

Une fois installé et démarré, la structure suivante est générée dans le répertoire ~/.thebotcompany/ :

~/.thebotcompany/
├── keys.json              # API Keys chiffrées
├── db.sqlite              # Base de données du suivi des issues
├── config.yaml            # Configuration globale
└── logs/                  # Journaux d’exécution

Votre répertoire de projet/
├── workers/               # Définition des compétences des agents ouvriers
│   ├── leo.md             # Frontmatter : reports_to, role, model
│   └── maya.md
├── workspace/             # Espaces de travail de chaque agent
│   ├── athena/note.md
│   ├── ares/note.md
│   └── leo/note.md
└── .tbc/                  # Configuration au niveau projet (générée à la création du projet)

---

Étapes d’installation, pas à pas

Étape 1 : installer TheBotCompany

npm install -g thebotcompany

Vérifier l’installation :

tbc --version

Étape 2 : démarrer le service

tbc start

Lors de la première exécution, vous serez invité à configurer successivement :

1. Mot de passe d’accès au Dashboard en écriture — pour protéger les actions d’écriture (pause, reprise, modification de configuration)
2. Numéro de port — par défaut 3100 ; appuyez sur Entrée pour accepter la valeur par défaut

? Set a password for dashboard write access: ********
? Port to run the dashboard (default 3100):

Une fois le démarrage réussi, le Dashboard est accessible à http://localhost:3100. Par défaut, il est en mode lecture seule ; après connexion seulement, vous pourrez agir.

Étape 3 : configurer l’API Key

Ouvrez le Dashboard (http://localhost:3100), cliquez sur Settings en haut à droite, puis ajoutez votre API Key dans le panneau Keys. Vous pouvez aussi la détecter automatiquement à la première exécution via des variables d’environnement :

# À ajouter dans .bashrc ou .zshrc :
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...

Étape 4 : créer un projet via le Dashboard

1. Ouvrez http://localhost:3100
2. Cliquez sur New Project et remplissez :
   • Repository URL — l’URL de votre Repo GitHub (nécessite que gh ait les droits)
   • Provider — choisissez le Provider LLM
   • Model Tier — les modèles utilisés par niveau (high/mid/low)
3. Cliquez sur Create : la main est donnée à Athena pour commencer le travail

---

Détails de l’architecture de collaboration à trois rôles

C’est la conception la plus centrale de TheBotCompany : en la comprenant, vous saurez comment tout le système fonctionne.

Trois rôles de gestion fixes

La boucle complète de Cycle

Phase PLANNING (Athena)
  → Athena + ses agents ouvriers se mettent en marche
  → Recherche, évaluation, brainstorming
  → Définition des jalons → passage à IMPLEMENTATION

Phase IMPLEMENTATION (Ares)
  → Ares + ses agents ouvriers (jusqu’à N cycles)
  → Ares annonce terminé → passage à VERIFICATION
  → Dépassement du budget de cycles → retour à PLANNING pour réévaluer

Phase VERIFICATION (Apollo)
  → Apollo + ses agents ouvriers se mettent en marche
  → Apollo valide → passage au prochain PLANNING
  → Apollo rejette → retour à IMPLEMENTATION pour corriger

Comment fonctionnent les agents ouvriers

Les Managers (Ares / Athena / Apollo) « recrutent » les agents ouvriers en créant des fichiers .md dans le répertoire {project_dir}/workers/. Chaque fichier contient un frontmatter YAML fixe :

---
reports_to: ares          # À qui faire un rapport
role: Frontend Engineer   # Description du rôle
model: mid                # Quel modèle utiliser
---

# Frontend Engineer

Vous êtes un ingénieur front-end chargé de mettre en œuvre les composants UI et la logique d’interaction.

Quand le Manager attribue une tâche à un ouvrier, il n’en attribue qu’une par agent et par cycle — il n’est pas autorisé d’en empiler cinq d’un coup. Une fois la tâche terminée, le Manager lit note.md dans l’espace de travail pour comprendre le contexte, puis décide de l’étape suivante.

Mode de communication entre agents

Les agents ne discutent pas directement : ils coordonnent via un Issue Tracker intégré :

• Ares a besoin de l’avis d’Athena → créez une Issue dans l’Issue Tracker et assignez-la à Athena
• Un Worker rencontre un problème → crée une Issue, le Manager la voit et la traite
• Besoin d’intervention humaine → crée une GitHub Issue, dont le titre commence par HUMAN: ; vous vous connectez à GitHub pour la traiter

---

Démonstration complète du flux de développement

Step 1 : créer un projet via Dashboard

Ouvrez le Dashboard, cliquez sur New Project :

Repository: https://github.com/your-username/your-repo
Provider: Anthropic
Model: claude-sonnet-4

Après la création du projet, une carte apparaît sur le Dashboard. Son statut est PLANNING et Athena commence à travailler.

Step 2 : observer le processus de planification d’Athena

Dans le panneau Agent Reports du Dashboard, vous pouvez voir la production d’Athena. Elle fait notamment :

• Lire le README du projet et le code existant pour comprendre la situation
• Rechercher des solutions techniques pertinentes et des meilleures pratiques
• Évaluer la faisabilité de la demande
• Définir le premier jalon et son budget (combien de Cycles)

Une fois les jalons définis, le système bascule automatiquement vers IMPLEMENTATION, et Ares se lance.

Step 3 : Ares exécute et implémente

Le statut du Dashboard passe à IMPLEMENTATION et Ares commence à travailler :

1. Recruter des ouvriers — Ares crée workers/leo.md, workers/maya.md, etc.
2. Distribuer les tâches — à chaque Cycle, une tâche spécifique est confiée à un seul ouvrier
3. Revue des PR — après l’envoi des PR par les ouvriers, Ares effectue un Code Review
4. Contrôle du Cycle — si un Cycle n’est pas terminé, on le renvoie au cycle suivant pour réessayer

Vous pouvez envoyer directement des messages à Ares via le panneau Chat du Dashboard pour ajuster la direction ou ajouter du contexte.

Step 4 : validation par Apollo

Quand Ares annonce la fin du jalon, le système passe à VERIFICATION et Apollo se lance :

→ Apollo lit les changements de code
→ Exécute les tests de validation (via GitHub Actions)
→ Vérifie si les exigences du jalon sont respectées
→ Si c’est bon → entrer dans le prochain PLANNING
→ Si ce n’est pas bon → renvoyer vers IMPLEMENTATION en indiquant ce qui ne va pas

Le niveau d’exigence d’Apollo est plus élevé que celui d’Ares. Il y a donc souvent des cas où « Ares pense que c’est bon, mais Apollo rejette » : c’est normal, ce n’est pas un bug.

Step 5 : intervention humaine (si nécessaire)

Lorsqu’un agent rencontre quelque chose qui nécessite vraiment un jugement humain, il crée une GitHub Issue qui commence par HUMAN: :

HUMAN: Pour la page de connexion, OAuth ou nom d’utilisateur et mot de passe ?
Répondez à cette Issue sur GitHub : l’agent poursuivra selon votre réponse.

Après votre réponse, Ares continue l’exécution. Si vous jugez qu’une intervention n’est pas nécessaire, vous pouvez directement mettre le projet en pause sur le Dashboard.

---

Détails des fonctionnalités du Dashboard

Le Dashboard de TheBotCompany est le centre de contrôle de tout le système : tous les statuts sont visibles clairement.

Vue d’ensemble des projets

La page d’accueil affiche toutes les cartes de projet ; chaque carte indique :

• L’étape actuelle (PLANNING / IMPLEMENTATION / VERIFICATION)
• Le compteur du cycle / d’epoch actuel
• Une barre de progression des jalons
• Le résumé du dernier Agent Report

Agent Reports

L’historique de sortie de chaque projet : rendu Markdown pris en charge et résumés automatiques. Si la sortie d’un cycle est particulièrement longue, le Dashboard la compresse automatiquement et n’affiche que les conclusions clés.

Issue Tracker

La coordination entre agents se fait ici :

• Filtrer par projet
• Filtrer par statut (Open / In Progress / Resolved)
• Filtrer par agent
• Panneau dédié Human Issues qui liste toutes les demandes d’escalade nécessitant votre intervention

Chat

Entrée de conversation directe intégrée au Dashboard : vous pouvez choisir n’importe quel projet, puis envoyer un message au Manager correspondant afin d’ajouter du contexte ou d’ajuster la direction. Réponses en streaming et téléversement d’images pris en charge.

Suivi des coûts

Détail des frais pour chaque projet et chaque agent :

• Coût du Last Cycle
• Coût moyen sur 24 heures
• Coût total cumulé

En combinaison avec Budget Controls, vous pouvez définir une limite glissante de budget sur 24h : si elle est dépassée, l’agent se met automatiquement en sommeil.

Controls

Boutons rapides dans le Dashboard :

• Pause / Resume — mettre le projet en pause et le reprendre (nécessite une connexion)
• Skip Sleep — ignorer l’intervalle de sommeil prédéfini et démarrer immédiatement le cycle suivant
• Kill Run / Cycle / Epoch — arrêter de force l’exécution en cours
• Bootstrap — redémarrer à partir d’un jalon spécifié

---

Multi-Provider et gestion du Key Pool

Liste des Providers pris en charge

TheBotCompany intègre la prise en charge de 15+ LLM Providers :

Fonctionnement du Key Pool

Dans le panneau Keys de Settings, vous pouvez ajouter plusieurs clés pour le même Provider et définir un ordre de priorité. À l’exécution :

1. Le système utilise en premier la clé ayant la priorité la plus élevée
2. Si la clé déclenche une limite de débit (429) ou si le quota est insuffisant → bascule automatique vers la clé suivante
3. Une fois le temps de refroidissement terminé, la clé redevient disponible et est réintégrée dans la rotation

C’est particulièrement utile pour les projets qui tournent longtemps : vous n’avez pas à vous inquiéter qu’une clé unique soit épuisée et immobilise toute l’équipe d’agents.

Configuration des Model Tiers

Chaque projet peut personnaliser les modèles utilisés par niveau :

# config .tbc/config.yaml au niveau du projet
model_tiers:
  high: claude-opus-4       # Architecture complexe, raisonnement profond
  mid: claude-sonnet-4      # Par défaut, équilibre entre capacités et coût
  low: claude-haiku-3       # Tâches simples et répétitives, mise en forme

Vous pouvez aussi modifier ces réglages via l’interface dans Settings, panneau Model Tier Overrides, sans toucher au fichier de configuration.

---

Dépannage des problèmes fréquents

Q1 : après tbc start, le Dashboard ne s’ouvre pas et affiche Connection Refused

Cause : le port est déjà utilisé, ou le service ne s’est pas démarré correctement.

Étapes de vérification :

# 1. Vérifier si tbc est en cours d’exécution
tbc status

# 2. Si ce n’est pas le cas, démarrer manuellement et observer la sortie d’erreur
tbc dev

# 3. Si le port est occupé, utiliser un autre port
TBC_PORT=3200 tbc start

---

Q2 : l’équipe d’agents reste bloquée en PLANNING et ne passe jamais en IMPLEMENTATION

Cause : Athena fait une enquête approfondie ou attend les résultats des agents ouvriers ; aucun jalon n’a encore été défini.

Solution :

Ouvrez Dashboard → Agent Reports pour consulter la sortie la plus récente d’Athena. Si elle attend le résultat d’un agent ouvrier, vous pouvez utiliser /tbc logs pour vérifier dans les logs du serveur si elle est bloquée. Si elle est effectivement bloquée, envoyez directement un message à Athena depuis le panneau Chat du Dashboard : « Veuillez définir le premier jalon sur la base des informations existantes, sans attendre plus de recherches. »

---

Q3 : aucun PR GitHub n’est créé automatiquement, et l’agent signale une erreur de permissions dans l’Issue Tracker

Cause : le CLI gh n’est pas correctement authentifié, ou les droits du Token sont insuffisants.

Étapes de vérification :

# 1. Vérifier l’état de connexion de gh
gh auth status

# 2. Si vous n’êtes pas connecté, réauthentifiez-vous (droits repo requis)
gh auth login --scopes repo

# 3. Vérifier que l’URL remote dans le répertoire du projet est correcte
cd /path/to/your-project
git remote -v

---

Q4 : Apollo rejette sans cesse les implémentations d’Ares, provoquant une boucle infinie de Cycle

Cause : la direction de correction d’Ares n’est pas cohérente avec ce qu’attend Apollo, ou la définition du jalon n’est pas assez claire.

Solution :

Dans le panneau Chat du Dashboard, envoyez à Ares : « La raison du rejet d’Apollo est [coller les commentaires précis du rapport Apollo]. Avant de corriger, veuillez d’abord comprendre les critères d’Apollo et valider avec Apollo la direction à prendre. »

Si les critères d’Apollo sont trop stricts, vous pouvez demander à Athena d’ajuster les conditions d’acceptation du jalon pendant la phase PLANNING.

---

Q5 : les coûts dépassent largement les attentes ; vous voulez arrêter immédiatement tous les agents

Solution :

# Méthode 1 : action via Dashboard
# Connexion au Dashboard → carte de chaque projet → Controls → Pause

# Méthode 2 : pause via CLI
tbc stop

# Méthode 3 : définir une limite de budget (effective au prochain démarrage)
# Dans Dashboard Settings → Budget Controls, définir la limite de budget sur 24h

---

Q6 : vous avez ajouté plusieurs API Key, mais l’agent continue d’utiliser la même clé et finit par dépasser la limite

Cause : l’ordre de priorité du Key Pool n’est peut-être pas le bon, ou le refroidissement lié à la limitation de débit n’est pas terminé.

Solution :

Dans Dashboard Settings → panneau Keys, vérifiez l’état de chaque clé :

• Active — utilisée normalement
• Cooldown — limitation de débit déclenchée, période de refroidissement en cours
• Exhausted — quota épuisé

Si une clé reste trop longtemps en Cooldown, déplacez-la manuellement en bas de la liste des clés afin que le système bascule sur la suivante.

---

Lecture complémentaire et pistes d’approfondissement

1. Personnaliser les compétences des agents ouvriers

Créez de nouveaux fichiers .md dans le répertoire workers/ pour étendre les capacités de l’équipe :

---
reports_to: ares
role: DevOps Engineer
model: mid
---

# DevOps Engineer

Vous êtes un ingénieur DevOps, maîtrisant les pipelines CI/CD, la conteneurisation et l’infrastructure as code.

Le Manager détectera automatiquement les nouveaux agents ouvriers ajoutés ; lors du prochain Cycle, ils pourront être planifiés.

2. Intégrer un Provider personnalisé

Si vous devez brancher un service LLM interne à l’entreprise (au format compatible OpenAI ou Anthropic), dans Settings → Keys → Add Custom Provider :

{
  "name": "my-internal-llm",
  "baseUrl": "https://llm.internal.company.com/v1",
  "apiKey": "sk-internal-...",
  "model": "gpt-4"
}

3. Intégration approfondie avec GitHub Actions

Le design des agents de TheBotCompany encourage à exécuter les tests et builds longs dans GitHub Actions. Dans les fichiers de compétences des agents ouvriers, spécifiez :

Ne lancez jamais directement des tests qui durent plus de 5 minutes dans le terminal. Tous les suites de tests doivent être déclenchées via GitHub Actions.

Ainsi, lorsque l’agent est tué à cause d’un timeout de Cycle, les codes déjà soumis et les résultats CI ne seront pas perdus.

4. Gestion multi-projets et vue d’ensemble

Si vous exécutez plusieurs projets en parallèle (maintenance open source, Side Project, projets commerciaux), le Dashboard unifié de TheBotCompany vous permet de voir, sur une seule page, l’état, les dépenses et la répartition des problèmes de tous les projets. Utilisez les Project Filters au niveau supérieur pour changer rapidement, et le panneau Human Issues pour traiter toutes les demandes d’escalade sans rien oublier de ce qui nécessite votre décision.

5. Contrôle fin du budget et des coûts

Par défaut, la limite glissante de budget sur 24h est globale. Si vous souhaitez définir des budgets différents pour des projets différents, vous pouvez exécuter plusieurs instances de TheBotCompany (avec des répertoires TBC_HOME différents) : chaque instance gère indépendamment un ensemble de projets et de budgets, sans interférer.