Étude de cas : summoner

1. Contexte et objectifs

Problématique

Avec 48 projets utilisant Claude Code dans le lab (10 581 sessions totales), gérer les sessions manuellement devient un frein :

• Contexte perdu entre les sessions (--resume sous-utilisé)
• Pas de visibilité sur les coûts par projet
• Tâches récurrentes (audits, mises à jour) oubliées ou dupliquées
• Aucune orchestration cross-projet possible
• Pas de métriques sur la qualité et la productivité

Vision

2. Parcours utilisateur

Summoner est un dashboard web (port 7777) qui détecte automatiquement les projets présents dans ~/lab. Voici le parcours quotidien d'un développeur.

Vue projets : la base de tout

Au lancement, Summoner scanne ~/lab et affiche tous les projets détectés (via package.json, Cargo.toml, pyproject.toml, .git). Chaque projet montre :

• Son stack détecté (node, cargo, python)
• La branche git courante et l'état dirty/clean
• Le nombre d'agents Claude et de commandes configurées (.claude/)
• Un health score basé sur le taux de succès des sessions, le checklist score et l'historique
• Le coût cumulé en USD par projet
• Son archétype : experiment, utility, product ou platform

Sessions : travailler sur un projet

Deux modes pour ouvrir une session Claude sur un projet :

Chaque session affiche en temps réel : le coût en USD, le nombre de tool calls par type (Read, Write, Bash, Agent), la durée, et le statut (running, stopped, error). La reprise est possible via --resume pour ne pas perdre le contexte.

Kanban : organiser le travail

Le tableau kanban est le centre de commande. Chaque projet a ses tâches réparties en 5 colonnes :

Le workflow concret :

1. Créer une tâche dans le backlog (titre, priorité, labels, dépendances)
2. Glisser vers "Todo" : la task queue la prend automatiquement quand un slot est libre
3. Summoner spawne une session oneshot avec le prompt de la tâche → la carte passe en "In Progress"
4. Le résultat apparaît en temps réel dans le chat panel
5. À la fin → la tâche passe en "Done" (ou "Failed" avec possibilité de retry)

Loops : tâches récurrentes

Le loop engine automatise les tâches répétitives. Exemples concrets d'utilisation :

Chaque loop conserve son contexte (--resume) : le Claude qui fait l'audit à 8h sait ce qu'il a trouvé à 8h la veille.

Golems :agents autonomes

Un golem est un agent Claude qui travaille de manière proactive sur un projet. Contrairement aux loops (tâches prédéfinies), le golem décide lui-même ce qu'il faut faire :

Chaque golem a un budget max (en USD et en nombre de tâches) et peut être pausé/repris à tout moment.

Workflows :orchestration multi-étapes

Pour les processus complexes qui enchaînent plusieurs actions. Exemple d'un workflow de release :

Les workflows peuvent être déclenchés manuellement, par cron, par webhook, ou automatiquement à la fin d'une session ou d'un git push.

Coûts et budget

Summoner agrège les coûts de toutes les sessions Claude par projet et par jour :

• Coût par session : affiché en temps réel pendant l'exécution
• Coût par projet : cumul avec historique et tendance
• Coût par tâche : permet de mesurer l'efficience ($ par tâche terminée)
• Alertes budget : alerte quand un projet dépasse $5/jour ou quand le total dépasse 2x la moyenne
• Quota quotidien : warning à 80%, block à 100%

Bootstrap :créer un nouveau projet

Summoner peut scaffolder un nouveau projet complet en 5 étapes :

1. Initialize : manifest (package.json / Cargo.toml), git init, .gitignore adapté au langage
2. Dependencies & tooling : package manager, linter (Biome/ESLint/Clippy), formatter
3. Claude setup : CLAUDE.md structuré, répertoire .claude/, agents, commandes, mémoire
4. Source control : git hooks (lefthook), CI/CD template
5. Architecture docs : README, ARCHITECTURE.md, CHANGELOG

Chaque étape est un prompt Claude auto-suffisant avec checklist de validation. Support de TypeScript, Python, Rust, GDScript et JavaScript.

3. Architecture technique

Monorepo - 4 packages

summoner/
├── packages/
│   ├── core/          # 18 000+ LOC - Business logic
│   │   ├── store.ts           # SQLite WAL, 3 700 LOC
│   │   ├── session-manager.ts # Claude CLI lifecycle, 1 400 LOC
│   │   ├── scanner.ts         # Auto-detect ~/lab, 1 600 LOC
│   │   ├── task-queue.ts      # Concurrency + deps, 500 LOC
│   │   ├── loop-engine.ts     # Tâches récurrentes, 370 LOC
│   │   ├── golem-engine.ts    # Agents autonomes, 670 LOC
│   │   ├── workflow-engine.ts # Multi-step orchestration, 750 LOC
│   │   ├── alert-engine.ts    # Anomaly detection, 250 LOC
│   │   └── ...14 autres modules
│   │
│   ├── daemon/        # 3 600 LOC - Fastify 5 REST + WebSocket
│   │   └── server.ts          # Routes, event broadcasting, lifecycle
│   │
│   ├── web/           # Lit 3 SPA - 20+ composants
│   │   ├── kanban-board.ts    # Drag & drop tasks
│   │   ├── chat-panel.ts      # Terminal viewer + syntax highlighting
│   │   ├── golem-panel.ts     # Agent monitoring
│   │   └── factory-dashboard.ts # Production metrics
│   │
│   └── mcp/           # MCP server - Claude contrôle Summoner
│       └── index.ts           # Tool calls bridge
│
├── summoner.db        # SQLite (auto-created, WAL mode)
└── scripts/dev.ts     # Blue-green dev orchestrator

Stack technique

Design decisions

3. Engines :les moteurs de summoner

Session Manager

Gère le cycle de vie des processus Claude CLI :

Task Queue + Kanban

Exécution automatique des tâches avec gestion de concurrence :

• Concurrence : max 2 sessions simultanées (partagé avec LoopEngine)
• Tick : toutes les 5 secondes :détecte les sessions mortes, débloque les dépendances
• Colonnes kanban : backlog → todo → in_progress → review → done
• Model routing : Haiku pour la doc, Sonnet pour les audits/loops, auto-sélection du modèle le moins cher
• Circuit breaker par projet : 3 échecs consécutifs → cooldown de 5 min

Loop Engine

Tâches récurrentes sans réinitialisation de contexte :

// Exemple de configuration loop
{
  intervalMs: 900_000,   // Toutes les 15 minutes
  maxRuns: 100,          // Arrêt après 100 exécutions
  enabled: true,
  // → Le loop engine tick toutes les 10s
  // → Jusqu'à 3 loop tasks concurrentes
  // → Health check PID-based pour auto-unstick
}

Golem Engine - Agents autonomes

Workflow Engine

Orchestration multi-étapes avec 8 types de steps :

Triggers : manual, cron, webhook, on_session_end, on_push.

4. Observabilité et alertes

Alert Engine

Factory Metrics

Métriques de production pour mesurer l'efficacité du lab :

• Throughput : tâches completed/failed par jour
• Lead time : heures moyennes de queued → completed
• Cost efficiency : coût par tâche terminée
• Quality rate : % de sessions passant le quality gate
• Capacity estimate : backlog actuel, tasks/jour moyennes, jours restants
• Budget par projet : dépensé / budget / pourcentage

Recommendation Engine

Insights proactifs avec actions - tourne toutes les 60 secondes :

// Types de recommandations
cost_spike        → "Coût anormal sur granit-golem : $12 aujourd'hui vs $3 en moyenne"
circuit_breaker   → "3 échecs consécutifs sur un cas client multi-agent : session auto-stoppée"
stuck_task        → "Tâche #42 bloquée depuis 45 min : action: retry ou stop"
loop_failures     → "Loop 'daily-audit' échoue depuis 3 runs"
queue_backlog     → "15 tâches en attente : capacité estimée : 3 jours"
quota_warning     → "80% du budget quotidien atteint"

5. Utilisation de Claude Code

Configuration CLAUDE.md

## Stack
| Package | Tech | Rôle |
|---------|------|------|
| @summoner/core   | TypeScript, SQLite, node-pty | Engine |
| @summoner/daemon | Fastify 5, WebSocket        | API    |
| @summoner/web    | Lit 3, Vite 6, xterm.js     | SPA    |

## Conventions
- Monorepo npm workspaces
- TypeScript strict, ESM only
- Lit 3 avec decorators pour les web components
- SQLite WAL mode pour la persistence
- WebSocket pour le real-time

## Principes
1. Zéro token waste - claude --resume pour les contextes
2. Loop engine - Tâches récurrentes sans réinitialisation
3. Real-time - WebSocket broadcast de tous les événements
4. Auto-scan - Détection automatique des projets ~/lab

## Process lifecycle
- startOneshot() retourne avant que le spawn soit validé
- Timeouts: 30min task, 10min prompt, 5min command
- Toujours émettre session:end dans error ET close
- Event listeners: cleanup explicite (pas de on() sans remove)

Méta-récursivité

6. Métriques et résultats

Analyse des 34 commits

Ratio fix/feat : 0.33

Volume de code

7. Problèmes rencontrés et solutions

8. Enseignements clés