agent-manager/ROADMAP.md

🗺️ ROADMAP agent-manager — vers le « super outil »

Version du document : 2.2 · Statut : propositions, non engagées Base : analyse du code v0.2.7 (Rust, 45+ tests, zéro dépendance runtime)

✅ Phase 0 livrée en v0.3.0 (2026-08-17) : issues #2 à #16 clôturées, 157 tests, release publiée sur Gitea. Les découpages des phases 1 à 3 sont en place sur Gitea (issues #25 à #80) : v0.4.0, v0.5.0, v1.0.

✅ Phase 1 livrée en v0.4.1 (2026-08-17) : 17/17 issues clôturées (#26–#42), 240+ tests. v0.4.0 a livré 13/17 (#26–#32, #34–#38) ; v0.4.1 complète avec le dashboard TUI (#33), les favoris/notes/tags (#39), les profils d'environnement (#40), les complétions dynamiques + man pages (#41) et le packaging officiel + CI (#42). Binaires Windows/Linux publiés sur Gitea — am self-update et les installateurs servent la v0.4.1.

---

📖 Sommaire

1. Résumé exécutif
2. Légende de lecture
3. Quick wins — valeur immédiate
4. État des lieux
5. Vision & principes
6. Socle technique : le modèle de données
7. Les 12 axes
8. Jalons versionnés
9. Indicateurs de succès (KPI)
10. Risques & garde-fous
11. Par où commencer

---

1. 📌 Résumé exécutif

am est aujourd'hui un excellent gestionnaire d'agents : 72 agents au catalogue, 9 méthodes d'installation, dépendances résolues automatiquement, processus pilotés, REPL avec passerelle shell, sauvegarde export/import.

Mais il est aveugle : il ne retient ni ce qui a été fait, ni quand, ni par quel agent, ni dans quel projet, ni avec quel résultat. Les logs sont du texte libre non interrogeable, l'état ne contient que les installations et le PID courant, l'historique est un simple fichier plat.

Cette roadmap transforme am en cockpit de votre parc d'agents IA :

Rôle	Promesse	Porté par
📓 Journal de bord	tout est tracé, rien ne se perd	Axe 1 (journal d'événements)
🔎 Rétroviseur	tout est cherchable en 2 secondes	Axes 2, 3, 4
📊 Tableau de bord	tout est mesuré	Axes 1, 5, 9
🤖 Copilote	il pilote à votre place	Axes 6, 7

Chiffres clés : 12 axes · ~55 fonctionnalités · 4 jalons (v0.3.0 → v1.0) · ~15 semaines de travail cumulé · 0 dépendance runtime ajoutée.

---

2. 📚 Légende de lecture

Symbole	Signification
P0	Fondations — à démarrer tout de suite (socle des autres axes)
P1	Court terme — après la phase 0
P2	Moyen terme
P3	Vision — long terme
⭐	Reprend une demande explicite de l'utilisateur
S	Effort : moins d'1 jour
M	Effort : 2 à 4 jours
L	Effort : 1 à 2 semaines
XL	Effort : plus de 2 semaines
⬜ / 🔨 / ✅	Proposé / En cours / Livré (rien n'est commencé aujourd'hui)

---

3. ⚡ Quick wins — valeur immédiate

Tous en effort S, phase P0, sans dépendance sur le socle. Livrables en quelques jours, à caler avant ou pendant la construction du journal.

Fonctionnalité	Commande	Apport
Voir les logs d'un agent	am logs claude-code (--follow)	tail des logs déjà écrits par process.rs
Filtres sur la liste	am list --running · --sort name,version,status	repérage instantané
Éditer la config sans éditeur	am config set key value	moins de friction YAML
Alias à la volée	am alias add cc claude-code	sans éditer le fichier
Historique propre	dédup + horodatage de history.txt	base saine pour l'axe 2
Doctor scriptable	am doctor --json	CI et monitoring
Ouvrir l'installation	am open claude-code	explorer le répertoire de l'agent
Version scriptable	am version --json	introspection des scripts

---

4. 🧭 État des lieux (points d'ancrage dans le code)

Brique actuelle	Fichier	Limite aujourd'hui
Catalogue 72 agents, alias, groupes	src/catalog.rs, config.yaml	recherche = sous-chaîne stricte, pas de ranking
Installation (9 méthodes), dépendances OS	src/installers/, src/deps.rs, src/toolchain.rs	solide — rien à redire
État local	src/state.rs (state.json v1)	installations + PID courant uniquement, aucun historique
Détection externe + cache	src/probe.rs	excellent pattern de cache — à généraliser
Processus	src/process.rs	logs non structurés, pas de sessions, pas de métriques
Journal applicatif	src/output.rs	texte libre horodaté, non interrogeable
REPL + passerelle shell	src/repl.rs (history.txt, session_id())	historique plat, pas de recherche ni de stats
Backup	src/commands/export_import.rs	manuel, pas de synchronisation

---

5. 🎯 Vision & principes directeurs

Vision : le cockpit unique du parc d'agents — journal de bord, rétroviseur, tableau de bord et copilote.

Principes :

1. Zéro dépendance runtime — tout est Rust pur et fichiers locaux (JSONL/JSON), jamais de base de données externe.
2. Local par défaut, opt-in pour le distant — la télémétrie n'existe que si l'utilisateur l'active ; tout le reste est 100 % local.
3. Contrats stables — les sorties --json sont la base des scripts et des futurs UI : champs ajoutés, jamais retirés.
4. Performance — écriture en append (JSONL), lectures par fenêtres temporelles, index dérivés régénérables, caches sur le modèle de probe.rs.
5. Livraison continue — chaque phase produit un binaire utilisable et testé ; la barre des 45+ tests monte à chaque jalon.

---

6. 🧱 Socle technique : le modèle de données

Tout dépend de ceci. À construire en premier, avant les commandes visibles.

state_dir/
  state.json            # v2 : + sessions_count, last_used (migration auto depuis v1)
  events.jsonl          # NOUVEAU — journal d'événements (source de vérité)
  events-202608.jsonl   # rotation mensuelle
  sessions.json         # NOUVEAU — registre des sessions (index dérivé)
  history/
    <session>.jsonl     # NOUVEAU — historique structuré du REPL
  projects.json         # NOUVEAU — agrégats par projet (recalculable)
  probe-cache.json      # existant — pattern de cache à suivre

Fichier	Rôle	Alimenté par	Reconstruction
events.jsonl	faits bruts (start, stop, run, install…)	process.rs, run_cmd.rs, install_cmd.rs, repl.rs, doctor_cmd.rs	source de vérité, jamais reconstruit
sessions.json	index des sessions	dérivé du journal	doctor --fix (rejoue le journal)
projects.json	agrégats par projet	dérivé du journal	doctor --fix
history/*.jsonl	commandes REPL	repl.rs	non (données primaires)
state.json v3	installations + résumé + annotations (★, notes, tags)	state.rs	partiellement (compteurs depuis le journal)

Règles : JSONL append-only pour les faits · JSON dérivés régénérables · migration additive (state v1 reste lisible partout) · doctor --fix répare tout ce qui peut l'être.

---

7. 🗂️ Les 12 axes

Axe 1 — 📊 Observabilité & statistiques d'utilisation ⭐

🎯 Savoir quoi a tourné, quand, combien de temps, avec quel taux de succès — et combien ça coûte.

Fonctionnalité	Effort	Phase
Journal d'événements events.jsonl (toutes les actions de am)	M	P0
am stats + --period 7d/30d/90d + --json (tableaux et barres ASCII)	M	P0
am top — classement des agents par utilisation	S	P1
am log — filtres agent/type/date, --follow	S → M	P0 → P1
am report — rapport hebdo/mensuel en markdown (top agents, échecs, changements)	M	P1
Suivi des coûts — tokens/€ par session quand l'agent expose son usage (Claude Code --output-format json, Codex…)	M	P2
am monitor — TUI temps réel : CPU/mémoire par PID, uptime, alertes	L	P2
Télémétrie anonyme opt-in (compteurs agrégés uniquement, jamais de chemins)	M	P3

am stats                    # vue globale
am stats claude-code --period 30d
am top                      # qui tourne le plus
am report --last-week       # digest markdown

Axe 2 — 💾 Historique des commandes ⭐

🎯 Gérer, rechercher et réutiliser tout ce qui a été tapé.

Fonctionnalité	Effort	Phase
Historique structuré : history/.jsonl (cmd, kind am/shell, cwd, durée, exit, agent) + migration de history.txt	M	P0
am history — filtres --kind, --cwd, --search, --failed, --session	M	P0
Ctrl-R + !! + !install + !42 + ^old^new dans le REPL	M	P1
am history --rerun 42 (réexécution confirmée)	S	P1
Playbooks : am history 12..25 --save deploy.yaml puis am playbook deploy.yaml	L	P2

am history --search "install" --failed
am history --rerun 42

Axe 3 — 🧭 Projets & workspaces ⭐

🎯 Centraliser quel agent travaille sur quel projet — automatiquement.

Fonctionnalité	Effort	Phase
Contexte auto au lancement : racine + branche git, stack détectée (Cargo.toml, package.json…), mis en cache	S	P0
am projects / am projects api — agents, sessions, durées, dernière activité	M	P1
Profils de projet dans config : default_agent, env, hooks	M	P1
am start (sans argument) = agent par défaut du dossier courant ; REPL contextuel	S	P1
am init — génère un agent-manager.yaml selon la stack détectée	S → M	P0
Templates : am init --template web	M	P2

am projects
am projects api
am init            # dans un projet Node → config pré-remplie

Axe 4 — 🗂️ Sessions centralisées ⭐

🎯 Un registre unique de toutes les sessions de tous les agents — consultable, reprenable, archivable.

Fonctionnalité	Effort	Phase
sessions.json + session_id() partagé (repl.rs) ; fin de session avec exit code et durée	M	P0
Réconciliation au démarrage : sessions interrompues (crash, reboot) marquées et datées	S	P0
am sessions — filtres agent/projet/statut ; show = résumé + extrait de log	M	P0
am timeline — vue chronologique unifiée de toute l'activité	M	P1
am sessions resume — relance avec les mêmes args/env/cwd	M	P1
am sessions export + rétention configurable (settings.sessions_retention_days)	M	P2

am sessions --status failed
am sessions show 20260815_143926_a1b2c3
am timeline --project api

Axe 5 — 🖥️ Tableau de bord

🎯 Voir l'état du parc d'un coup d'œil.

Fonctionnalité	Effort	Phase
am dashboard — TUI (ratatui/crossterm) : vue d'ensemble, activité en direct, stats, sessions, projets	L	P1
am web — serveur local + API JSON + page HTML embarquée avec graphiques	XL	P2

Axe 6 — 🤖 Automatisation & orchestration

🎯 Laisser am superviser et piloter seul le parc.

Fonctionnalité	Effort	Phase
Hooks on_install / on_start / on_stop / on_update (agent, projet, global) — via le runner existant	M	P0
am watch claude-code --restart-on-crash --notify	M	P1
Services : unités systemd / plists launchd / tâches Windows, am service install claude-code --autostart	L	P2
Planification : am schedule --daily update --all + check santé (cron / Task Scheduler)	M	P2
Orchestration de groupes : ordre, --parallel, attente de santé	L	P2
Conteneurs : profil docker/podman par agent (isolation à la demande)	L	P2
am doctor --watch — vérifications périodiques avec alertes	M	P2

Axe 7 — 🧠 Intelligence & catalogue

🎯 Trouver le bon agent, suivre leurs sorties, et comparer.

Fonctionnalité	Effort	Phase
Recherche fuzzy dans am search (typos, scoring, « vouliez-vous dire »)	M	P1
am compare a b — tableau côte à côte (méthode, deps, catégorie, activité)	S	P1
am news — dernières releases des agents installés (API GitHub/Gitea, cache)	M	P1
Catalogue distant : am catalog update / am catalog add	M	P2
am suggest "un agent pour du Python" — tags + usage réel	M	P2
am lab — benchmark : même tâche sur N agents, comparaison durée/résultat/coût	L	P2
Registre communautaire : publier son catalogue (Gitea) + am registry	L	P3
am ask "installe claude et lance-le" — langage naturel → commande am (fournisseur LLM configurable, optionnel)	L	P3

Axe 8 — 🔒 Sécurité & gouvernance

🎯 Protéger les secrets, tracer les changements, pouvoir revenir en arrière.

Fonctionnalité	Effort	Phase
am secret set OPENAI_KEY --agent claude-code (keyring OS) + injection --env automatique	M	P1
am audit — qui a modifié quoi quand (checksums des configs, événements)	M	P2
am update --rollback — backup automatique avant chaque mise à jour	M	P2
Politiques : pin de version, settings.update_policy	S	P2
Profils sandbox par agent (commandes/répertoires autorisés)	L	P3

Axe 9 — 🌐 Multi-machine & collaboration

🎯 Retrouver son cockpit partout, et le partager.

Fonctionnalité	Effort	Phase
Synchronisation git automatique : settings.sync_repo, am sync, push à la fermeture du REPL	L	P2
Partage de catalogue d'équipe : include par URL	S	P2
am migrate — assistant de transfert machine A → B	M	P2
am serve --token — API HTTP + WebSocket pour piloter à distance	XL	P3

Axe 10 — 🧩 Confort & personnalisation

🎯 Adapter am à sa façon de travailler.

Fonctionnalité	Effort	Phase
Favoris : am favorite / am unfavorite + ⭐ dans am list	S	P1
Notes : am note claude-code "utiliser pour …"	S	P1
Tags personnels : am tag claude-code python	S	P1
Raccourcis de commandes : settings.shortcuts (i → install, s → start)	S	P1
Profils d'environnement : am profile dev / prod (env + args + agent par profil)	M	P1
Thèmes couleurs du REPL	S	P2

Axe 11 — 🎛️ Modèles locaux

🎯 Étendre le cockpit aux modèles : ollama, llama.cpp, LM Studio.

Fonctionnalité	Effort	Phase
am models — inventaire : nom, taille disque, quantisation, dernière utilisation	M	P2
Lien agent ↔ modèle : am run mon-agent --model llama3.1	M	P2
doctor vérifie ollama / llama-server comme n'importe quel outil	S	P2
am models prune — purge des modèles inutilisés	S	P2

Axe 12 — 🛠️ Écosystème & expérience développeur

🎯 Rendre am disponible partout et contribuable.

Fonctionnalité	Effort	Phase
Fixtures d'événements rejouables + tests de bout en bout du journal	S	P0
Packaging officiel : winget, scoop, deb/rpm, Homebrew + CI de release	M	P1
Complétions dynamiques (agents installés, groupes personnalisés)	S	P1
Man pages + documentation générée	S	P1
i18n : messages EN/FR	L	P2
Plugin scripts (hooks avancés, intégration CI)	M	P2

---

8. 🚀 Jalons versionnés

Jalon	Version	Contenu principal	Durée	Critère de sortie
J0 — Fondations	v0.3.0	events.jsonl, sessions, am stats, am log, am history, am init, quick wins	≈ 2 sem	100 % des actions tracées · 100+ tests
J1 — Cockpit	v0.4.0	recherche fuzzy, Ctrl-R, projects, timeline, dashboard TUI, hooks, secret, favoris, packaging	≈ 3 sem	retrouver n'importe quelle action passée en < 2 s
J2 — Automatisation	v0.5.0	watch, services, schedule, news/compare, catalogue distant, lab, models, sync	≈ 4 sem	parc auto-supervisé (crash = redémarrage + alerte)
J3 — Plateforme	v1.0	am web, am serve, am ask, registry, télémétrie opt-in, sandbox	≈ 6 sem	dashboard web complet + API distante

---

9. 📈 Indicateurs de succès (KPI)

Indicateur	Cible
Part des actions tracées dans events.jsonl	100 % dès la v0.3.0
Temps pour retrouver une commande ou session passée	< 2 s
am list à chaud, journal actif	< 100 ms
Dépendances runtime ajoutées	0
Couverture de tests	≥ 100 tests en v0.3, +25 par jalon
Contrats --json cassés entre versions mineures	0

---

10. ⚠️ Risques & garde-fous

1. ADN « zéro runtime » : toute dépendance nouvelle est compilée dans le binaire, jamais requise à l'exécution.
2. Performance : le journal grossit — fenêtres temporelles, index dérivés, rotation mensuelle, caches façon probe.rs.
3. Vie privée : local par défaut ; télémétrie opt-in, agrégée, anonyme.
4. Contrats --json : ajout de champs sans retrait (scripts utilisateurs).
5. Compatibilité : migrations additives ; les exports 0.2.x restent importables en 0.3+.
6. Complexité UX : les fonctions avancées restent derrière settings.experimental jusqu'à maturité.
7. Périmètre : rester un orchestrateur — ne pas réimplémenter les fonctionnalités propres aux agents (tokens, MCP, prompts), sauf valeur transversale (stats, sessions, secrets, coûts).

---

11. 🏁 Par où commencer

Le suivi est en place sur Gitea : 4 milestones (v0.3.0 → v1.0), 22 labels (P0–P3, axe-1…axe-12, S/M/L/XL, quick-win, epic) et les issues ci-dessous. Chaque PR doit référencer son issue avec closes #N pour une clôture automatique. Ordre de construction proposé pour la phase 0 — chaque étape est un PR indépendant et testé :

1. PR 1 — src/events.rs : journal JSONL + rotation + tests.
2. PR 2 — instrumentation start/stop/run (process.rs, run_cmd.rs) — dépend de PR 1.
3. PR 3 — state.json v2 + migration additive — dépend de PR 1.
4. PR 4 — sessions.json + am sessions + réconciliation — dépend de PR 2.
5. PR 5 — am stats + am log (lecture du journal) — dépend de PR 2.
6. PR 6 — historique structuré + am history (migration de history.txt).
7. PR 7 — am init + détection de contexte (git, stack, cache) — dépend de PR 1.
8. En parallèle — les quick wins de la section 3 : am logs #9 · am list --sort #10 · am config set #11 · am alias add #12 · dedup history.txt #13 · am doctor --json #14 · am version --json #15 · am open #16.

Épique de suivi : issue #1 (Phase 0).

Phase 1 — Cockpit (v0.4.0) — découpage créé le 2026-08-17

Épique : issue #25 · milestone v0.4.0 · 17 issues.

#	Issue	Effort
#26	Recherche fuzzy dans am search	M
#27	Ctrl-R + réexécution dans le REPL	M
#28	am history --rerun N	S
#29	am projects + profils de projet	M
#30	am start contextuel (dépend de #29)	S
#31	am timeline (vue chronologique unifiée)	M
#32	am sessions resume	M
#33	am dashboard (TUI temps réel)	L
#34	Hooks on_install/on_start/on_stop/on_update	M
#35	am watch --restart-on-crash --notify	M
#36	am secret (keyring OS) + injection --env	M
#37	am top + am report (rapport hebdo/mensuel)	M
#38	am log --follow (flux en direct)	S
#39	Favoris, notes et tags personnels	M
#40	Profils d'environnement (am profile dev/prod)	M
#41	Complétions dynamiques + man pages	S
#42	Packaging officiel (winget/scoop/deb/Homebrew) + CI	M

Critère de sortie du jalon : retrouver n'importe quelle action passée en moins de 2 secondes.

Phase 2 — Automatisation (v0.5.0) — découpage créé le 2026-08-17

Épique : issue #47 · milestone v0.5.0 · 27 issues.

#	Issue	Effort
#49	Suivi des coûts — tokens/€ par session	M
#50	am monitor — TUI temps réel (CPU/mémoire par PID, alertes)	L
#51	Playbooks — am history --save + am playbook	L
#52	✅ Templates — am init --template web/python/rust/cli (substitution + validation)	M
#53	✅ am sessions export + rétention configurable (sessions_retention_days)	M
#54	am web — serveur local + API JSON + graphiques	XL
#55	Services système — am service install (systemd/launchd/tâches Windows)	L
#56	Planification — am schedule (--daily update --all, check santé)	M
#57	Orchestration de groupes (ordre, --parallel, attente de santé)	L
#58	Conteneurs — profils docker/podman par agent	L
#59	am doctor --watch — vérifications périodiques avec alertes	M
#60	✅ Catalogue distant — am catalog update / am catalog add	M
#61	✅ am suggest — « un agent pour du Python » (tags + usage réel)	M
#62	am lab — benchmark : même tâche sur N agents	L
#63	✅ am audit — qui a modifié quoi quand	M
#64	✅ am update --rollback — backup automatique avant mise à jour	M
#65	✅ Politiques — pin de version, settings.update_policy	S
#66	Synchronisation git automatique — am sync	L
#67	✅ Partage de catalogue d'équipe (include par URL)	S
#68	am migrate — assistant de transfert machine A → B	M
#69	✅ Thèmes couleurs du REPL	S
#70	✅ am models — inventaire des modèles locaux (ollama, llama.cpp, LM Studio)	M
#71	✅ Lien agent ↔ modèle — am run --model	M
#72	✅ doctor vérifie ollama / llama-server comme n'importe quel outil	S
#73	✅ am models prune — purge des modèles inutilisés	S
#74	i18n — messages EN/FR	L
#75	Plugin scripts (hooks avancés, intégration CI)	M

Critère de sortie du jalon : parc auto-supervisé (crash = redémarrage + alerte).

Phase 3 — Plateforme (v1.0) — découpage créé le 2026-08-17

Épique : issue #48 · milestone v1.0 · 5 issues.

#	Issue	Effort
#76	Télémétrie anonyme opt-in (compteurs agrégés uniquement)	M
#77	Registre communautaire — am registry (publication + recherche sur Gitea)	L
#78	am ask — langage naturel → commande am (fournisseur LLM optionnel)	L
#79	Profils sandbox par agent (commandes/répertoires autorisés)	L
#80	am serve --token — API HTTP + WebSocket pour piloter à distance	XL

Critère de sortie du jalon : dashboard web complet + API distante.

---

Document généré à partir de l'analyse du code (v0.2.7, commit d886de3). La phase 0 est livrée (v0.3.0) ; les découpages des phases 1 (v0.4.0), 2 (v0.5.0) et 3 (v1.0) sont en place sur Gitea (issues #25 à #80).