<div align="center">

<img src="./logo.svg" width="180" alt="oh-pi logo"/>

# 🐜 Ant Colony for Pi

**Transformer [pi-coding-agent](https://github.com/badlogic/pi-mono) d’un agent unique en un système d’exécution collaboratif inspiré d’une colonie de fourmis.**

Ce dépôt se recentre progressivement : d’un bundle de configuration pour pi vers un **plugin colony-first pour les tâches de code complexes**.
**Ant Colony for Pi** est désormais le nom produit public principal.
`oh-pi` reste aujourd’hui le nom du package/bootstrap pendant la transition, tandis que **`ant-colony` devient la capacité principale et la direction produit de long terme**.

[![npm](https://img.shields.io/npm/v/oh-pi)](https://www.npmjs.com/package/oh-pi)
[![license](https://img.shields.io/npm/l/oh-pi)](./LICENSE)
[![node](https://img.shields.io/node/v/oh-pi)](https://nodejs.org)

[English](./README.md) | [中文](./README.zh.md) | [Français](./README.fr.md)

```bash
npx oh-pi
```

</div>

---

## Clarification de nommage

Ce projet **n’est pas un fork** et **n’est pas affilié** à l’autre projet portant aussi le nom `oh-pi`.

Pour ce dépôt :
- **Ant Colony for Pi** = nom produit canonique
- `oh-pi` = nom actuel du package / bootstrap / transition

Plan de renommage :
- Marque : `Agent Colony`
- Nom canonique repo/package : `pi-agent-colony`
- [`docs/RENAMING-PLAN.md`](./docs/RENAMING-PLAN.md)
- [`docs/RENAME-EXECUTION-CHECKLIST.md`](./docs/RENAME-EXECUTION-CHECKLIST.md)
- [`docs/MIGRATION-MATRIX.md`](./docs/MIGRATION-MATRIX.md)
- [`docs/RELEASE-SEQUENCING.md`](./docs/RELEASE-SEQUENCING.md)
- [`docs/MIGRATION-ANNOUNCEMENT.md`](./docs/MIGRATION-ANNOUNCEMENT.md)

## Nouveau positionnement

### Ce n’est plus présenté comme un “gros pack de configuration”

Nous nous éloignons volontairement d’une définition du produit comme :
- un ensemble de thèmes, presets, skills et confort d’installation
- une surcouche façon “oh-my-zsh pour pi”

Nous définissons désormais le cœur du produit comme :
- **Ant Colony for Pi**
- **un plugin multi-agents pour les tâches de code complexes**
- **un moyen d’ajouter à pi l’exploration, la décomposition, l’exécution parallèle, la revue et la récupération**

### Quel problème cela résout

L’exécution par agent unique commence à montrer ses limites quand une tâche :
- touche **3 fichiers ou plus**
- exige une **compréhension ou refactorisation transversale**
- peut être découpée en **sous-tâches parallèles**
- nécessite une **boucle de revue et réparation après exécution**

Ant Colony ne cherche pas à remplacer pi. Son objectif est de lui donner une couche d’exécution plus robuste pour les tâches qui dépassent la zone de confort d’un agent unique.

## Démarrage en 30 secondes

```bash
npx oh-pi             # chemin legacy/bootstrap pendant la transition
npx pi-agent-colony   # chemin d’installation canonique
pi                    # utiliser la colonie dans pi
```

Pour l’instant, `oh-pi` reste le nom de compatibilité/bootstrap et continue d’installer les fichiers dans `~/.pi/agent/`.
Le nom canonique devient progressivement `pi-agent-colony`, tandis que le nom produit public reste **Agent Colony / Agent Colony for Pi**.

## Annonce de migration

Chemin d’installation canonique :

```bash
npx pi-agent-colony
pi install npm:pi-agent-colony
```

Chemin compatible legacy :

```bash
npx oh-pi
pi install npm:oh-pi
```

Détails :
- [`docs/MIGRATION-ANNOUNCEMENT.md`](./docs/MIGRATION-ANNOUNCEMENT.md)

## Voir d’abord la valeur de la colonie

### Si vous dites

```text
"Refactorer l’authentification session vers JWT, ajouter les tests, puis lancer une passe de régression."
```

### Ant Colony répond ainsi

```text
1. les scouts inspectent le code et identifient les frontières
2. les planners génèrent un pool de tâches et un ordre d’exécution
3. les workers modifient différents fichiers/modules en parallèle
4. les reviewers valident les changements et demandent des corrections si nécessaire
5. le résultat est résumé dans la conversation principale
```

C’est là la vraie différence produit : **débit sur tâches complexes, qualité de décomposition et fiabilité d’exécution**.

- [`docs/DEMO-SCRIPT.md`](./docs/DEMO-SCRIPT.md) — démo rapide de 2 minutes
- [`ROADMAP.md`](./ROADMAP.md) — jalons sous le nouveau positionnement
- [`DECISIONS.md`](./DECISIONS.md) — arbitrages produit et architecture
- [`docs/PRODUCT.md`](./docs/PRODUCT.md) — périmètre produit, cas d’usage et non-objectifs
- [`docs/ARCHITECTURE-REFACTOR.md`](./docs/ARCHITECTURE-REFACTOR.md) — plan de refactorisation des frontières plugin

## Quand utiliser Ant Colony

Privilégiez la colonie pour :

- les changements multi-fichiers
- les refactorisations transversales
- la décomposition de nouvelles fonctionnalités
- les compléments de tests, corrections et vérifications de régression
- les travaux d’ingénierie qui bénéficient du parallélisme

## Quand ne pas utiliser Ant Colony

Utilisez le flux pi classique lorsque :

- un seul fichier nécessite une modification claire et contenue
- vous avez besoin d’une réponse rapide ou d’une explication
- la tâche demande un contrôle humain strict étape par étape
- le travail est fondamentalement non parallèle et très concentré en contexte

## Ce que contient actuellement le dépôt

```
~/.pi/agent/
├── auth.json            Clés API (permissions 0600)
├── settings.json        Modèle, thème, niveau de réflexion
├── keybindings.json     Raccourcis Vim/Emacs (optionnel)
├── AGENTS.md            Directives IA par rôle
├── extensions/          8 extensions (7 par défaut + colonie)
│   ├── safe-guard       Confirmation des commandes dangereuses + protection des chemins
│   ├── git-guard        Points de contrôle stash auto + alerte dépôt sale
│   ├── auto-session     Nommage de session depuis le premier message
│   ├── custom-footer    Barre d'état améliorée (token/coût/temps/git/cwd)
│   ├── compact-header   Informations de démarrage simplifiées
│   ├── auto-update      Vérification des mises à jour au lancement
│   ├── bg-process       ⏳ **Bg Process** — Mise en arrière-plan automatique des commandes longues (serveurs dev, etc.)
│   └── ant-colony/      🐜 Essaim multi-agents autonome (optionnel)
├── prompts/             10 modèles (/review /fix /commit /test ...)
├── skills/              10 compétences (outils + design UI + workflows)
└── themes/              6 thèmes personnalisés
```

## Modes de configuration

| Mode | Étapes | Pour |
|------|--------|------|
| 🚀 **Rapide** | 3 | Choisir fournisseur → entrer clé → terminé |
| 📦 **Préréglage** | 2 | Choisir un profil de rôle → entrer clé |
| 🎛️ **Personnalisé** | 6 | Tout choisir soi-même |

### Préréglages

| | Inclut |
|---|--------|
| 🟢 **Complet** | Toutes extensions + colonie + bg-process |
| 🔵 **Propre** | Aucune extension |
| 🟣 **Colonie** | Colonie uniquement |

### Fournisseurs

Anthropic · OpenAI · Google Gemini · Groq · OpenRouter · xAI · Mistral · [FOXNIO](https://www.foxnio.com) (fournisseur Claude d'intérêt public recommandé)

Détection automatique des clés API depuis les variables d'environnement.

## 🐜 Colonie de fourmis

La fonctionnalité phare. Un essaim multi-agents modelé sur l'écologie réelle des fourmis — profondément intégré au SDK pi.

```
Vous : "Refactorer l'auth des sessions vers JWT"

oh-pi :
  🔍 Fourmis éclaireuses explorent le code (haiku — rapide, économique)
  📋 Pool de tâches généré à partir des découvertes
  ⚒️  Fourmis ouvrières exécutent en parallèle (sonnet — capable)
  🛡️ Fourmis soldats révisent tous les changements (sonnet — rigoureux)
  ✅ Terminé — rapport auto-injecté dans la conversation
```

### Architecture

Chaque fourmi est une `AgentSession` in-process (SDK pi), pas un sous-processus :

```
pi (processus principal)
  └─ ant_colony tool
       └─ queen.ts → runColony()
            └─ spawnAnt() → createAgentSession()
                 ├─ session.subscribe() → flux de tokens en temps réel
                 ├─ Zéro surcharge de démarrage (processus partagé)
                 └─ Auth et registre de modèles partagés
```

**Mode interactif :** La colonie tourne en arrière-plan — vous continuez à discuter. Un widget en temps réel affiche la progression, et les résultats sont auto-injectés à la fin.

**Mode print (`pi -p`) :** La colonie tourne de manière synchrone, bloque jusqu'à la fin.

### Pourquoi des fourmis ?

Les vraies colonies de fourmis résolvent des problèmes complexes sans contrôle central. Chaque fourmi suit des règles simples, communique par **pistes de phéromones**, et la colonie s'auto-organise. oh-pi reproduit directement ce modèle :

| Fourmis réelles | oh-pi |
|-----------------|-------|
| L'éclaireuse trouve la nourriture | L'éclaireuse scanne le code, identifie les cibles |
| Piste de phéromones | `.ant-colony/pheromone.jsonl` — découvertes partagées |
| L'ouvrière transporte la nourriture | L'ouvrière exécute la tâche sur les fichiers assignés |
| Le soldat garde le nid | Le soldat révise les changements, demande des corrections |
| Plus de nourriture → plus de fourmis | Plus de tâches → concurrence plus élevée (auto-adaptée) |
| Les phéromones s'évaporent | Demi-vie de 10 min — les infos obsolètes s'estompent |

### UI en temps réel

En mode interactif, la colonie affiche la progression en direct :

- **Barre de statut** — footer compact avec métriques réelles : tâches terminées, fourmis actives, appels d'outils, tokens de sortie, coût, durée
- **Ctrl+Shift+A** — panneau de détails en overlay avec liste des tâches, flux des fourmis actives et journal de la colonie
- **Notification** — résumé à la fin

Utilisez `/colony-stop` pour arrêter une colonie en cours.

### Protocole de signaux

La colonie communique via des signaux structurés, pour éviter toute supposition côté modèle :

| Signal | Signification |
|--------|---------------|
| `COLONY_SIGNAL:LAUNCHED` | Colonie démarrée en arrière-plan |
| `COLONY_SIGNAL:SCOUTING` | Vague d'éclaireuses en exploration/planification |
| `COLONY_SIGNAL:PLANNING_RECOVERY` | Boucle de récupération du plan en cours |
| `COLONY_SIGNAL:WORKING` | Exécution des tâches par les ouvrières |
| `COLONY_SIGNAL:REVIEWING` | Revue qualité par les soldats |
| `COLONY_SIGNAL:TASK_DONE` | Tâche terminée (jalon de progression) |
| `COLONY_SIGNAL:COMPLETE` | Mission terminée, rapport injecté |
| `COLONY_SIGNAL:FAILED` | Mission échouée avec diagnostic |
| `COLONY_SIGNAL:BUDGET_EXCEEDED` | Budget maximal atteint |

### Contrôle des tours

Chaque fourmi a un budget strict de tours pour éviter les exécutions incontrôlées :

Éclaireuse : 8 tours · Ouvrière : 15 tours · Soldat : 8 tours

### Sélection des modèles

La colonie détecte automatiquement les modèles disponibles et laisse le LLM choisir le meilleur par rôle :

| Rôle | Stratégie | Exemple |
|------|-----------|---------|
| Éclaireuse | Rapide & économique — lecture seule | `claude-haiku-4-5`, `gpt-4o-mini` |
| Ouvrière | Capable — modifie le code | `claude-sonnet-4-0`, `gpt-4o` |
| Soldat | Même que ouvrière ou légèrement moins cher | `claude-sonnet-4-0` |

Omettez les modèles pour utiliser le modèle de session actuel pour chaque fourmi.

### Rapport de coûts

La colonie suit le coût par fourmi et le total, rapporté dans le résumé final. **Le coût n'interrompt jamais l'exécution** — les limites de tours et le contrôle de concurrence gèrent les ressources.

### Déclenchement automatique

Le LLM décide quand déployer la colonie. Vous n'avez pas à y penser :

- **≥3 fichiers** à modifier → colonie
- **Flux parallèles** possibles → colonie
- **Un seul fichier** → exécution directe (pas de surcharge colonie)

### Concurrence adaptative

La colonie trouve automatiquement le parallélisme optimal pour votre machine :

```
Démarrage à froid  →  ceil(max/2) fourmis (démarrage rapide)
Exploration        →  +1 par vague, surveillance du débit
Débit ↓            →  verrouiller l'optimal, stabiliser
CPU > 85%          →  réduire immédiatement
429 rate limit     →  concurrence -1 + backoff (2s→5s→10s max)
Tâches terminées   →  réduire au minimum
```

### Sécurité des fichiers

Une fourmi par fichier. Toujours. Les tâches en conflit sont automatiquement bloquées et reprennent quand les verrous sont libérés.

## Compétences

oh-pi embarque 10 compétences en trois catégories.

### 🔧 Compétences outils

Scripts Node.js sans dépendances — aucune clé API requise.

| Compétence | Fonction |
|------------|----------|
| `context7` | Interroger la doc à jour des bibliothèques via Context7 API |
| `web-search` | Recherche DuckDuckGo (gratuit, sans clé) |
| `web-fetch` | Extraire le contenu d'une page web en texte brut |

```bash
# Exemples
./skills/context7/search.js "react"
./skills/web-search/search.js "typescript generics" -n 5
./skills/web-fetch/fetch.js https://example.com
```

### 🎨 Compétences design UI

Spécifications complètes avec tokens CSS, exemples de composants et principes de design. L'agent les charge quand vous demandez un style visuel spécifique.

| Compétence | Style | Préfixe CSS |
|------------|-------|-------------|
| `liquid-glass` | Verre translucide Apple WWDC 2025 | `--lg-` |
| `glassmorphism` | Flou givré + transparence | `--glass-` |
| `claymorphism` | Surfaces 3D douces en argile | `--clay-` |
| `neubrutalism` | Bordures épaisses, ombres décalées, contraste élevé | `--nb-` |

Chacune inclut `references/tokens.css` avec des propriétés CSS personnalisées prêtes à l'emploi.

```
Vous : "Construire un tableau de bord style liquid glass"
pi charge la compétence liquid-glass → applique les tokens --lg-, effets de verre, reflets
```

### 🔄 Compétences workflow

| Compétence | Fonction |
|------------|----------|
| `quick-setup` | Détecter le type de projet, générer la config .pi/ |
| `debug-helper` | Analyse d'erreurs, interprétation de logs, profilage |
| `git-workflow` | Branches, commits, PRs, résolution de conflits |
| `ant-colony` | Commandes et stratégies de gestion de colonie |

## Thèmes

| | |
|---|---|
| 🌙 **oh-pi Dark** | Cyan + violet, contraste élevé |
| 🌙 **Cyberpunk** | Magenta néon + cyan électrique |
| 🌙 **Nord** | Palette bleu arctique |
| 🌙 **Catppuccin Mocha** | Pastel sur fond sombre |
| 🌙 **Tokyo Night** | Crépuscule bleu + violet |
| 🌙 **Gruvbox Dark** | Tons chauds rétro |

## Modèles de prompts

```
/review    Revue de code : bugs, sécurité, performance
/fix       Corriger les erreurs avec des changements minimaux
/explain   Expliquer le code, du simple au détaillé
/refactor  Refactorer en préservant le comportement
/test      Générer des tests
/commit    Message Conventional Commit
/pr        Description de Pull Request
/security  Audit de sécurité OWASP
/optimize  Optimisation des performances
/document  Générer la documentation
```

## Modèles AGENTS.md

| Modèle | Focus |
|--------|-------|
| Développeur généraliste | Directives de codage universelles |
| Développeur full-stack | Frontend + backend + BDD |
| Chercheur en sécurité | Pentest & audit |
| Ingénieur Data & IA | MLOps & pipelines |
| 🐜 Opérateur de colonie | Orchestration multi-agents |

## Aussi un paquet Pi

Passez le configurateur, installez directement les ressources :

```bash
pi install npm:oh-pi
```

Ajoute tous les thèmes, prompts, compétences et extensions à votre configuration pi existante.

## Prérequis

- Node.js ≥ 20
- Au moins une clé API LLM
- pi-coding-agent (installé automatiquement si absent)

## Licence

MIT