Les agents de codage IA peuvent modifier des dizaines de fichiers, appeler des outils, deleguer a des sous-agents et corriger des echecs avant de rendre une reponse tres courte. Le diff final est visible; le chemin qui l’a produit l’est rarement.
patoles/agent-flow rend ce chemin inspectable. Cet outil Apache-2.0 visualise en temps reel Claude Code et Codex sous forme de graphe interactif : agents, appels d’outils, branches, retours, messages et activite sur les fichiers.
Agent Flow ne sert pas seulement a produire une jolie demonstration. Il repond a des questions operationnelles : quel sous-agent a bloque? Quel appel a ralenti la session? Pourquoi un fichier a-t-il ete relu plusieurs fois? Le travail parallele a-t-il bien converge? Quel prompt a cree des branches inutiles?
Le projet propose une application navigateur autonome, une application web lancee depuis les sources et une extension VS Code. Claude Code et Codex peuvent etre observes simultanement.
Ce qu’est Agent Flow
Agent Flow est une interface d’observabilite pour l’execution des agents de codage. Plutot qu’une transcription terminal lineaire, il cartographie les relations entre agent parent, agents delegues, appels d’outils, messages et retours.
Ses fonctions principales comprennent :
- un graphe de noeuds interactif avec zoom, deplacement et inspection
- la detection simultanee des sessions Claude Code et Codex
- des onglets pour plusieurs sessions actives
- une timeline et une transcription
- une carte d’attention sur les fichiers
- les comptes de tokens Codex issus des evenements officiels
- l’observation et le rejeu de logs JSONL
- une application navigateur et une extension compatible VS Code
Il s’agit d’une couche d’observabilite, pas d’un nouvel agent. Agent Flow ne decide pas comment travailler; il aide l’humain a comprendre comment le travail a ete realise.
Deux runtimes, deux pipelines
Claude Code et Codex exposent leur activite differemment. Agent Flow utilise donc un chemin de collecte adapte a chaque runtime.
Pour Claude Code, un serveur de hooks HTTP leger recoit directement les evenements. En mode source, le relay les transmet a l’interface Next.js avec Server-Sent Events, ce qui actualise le graphe presque immediatement.
Pour Codex, Agent Flow suit les fichiers ~/.codex/sessions/**/rollout-*.jsonl. Il respecte CODEX_HOME et lit le flux natif de Codex : appels d’outils, evenements de raisonnement et comptage des tokens.
Les deux sources peuvent etre observees ensemble. Les sessions portent leur runtime et apparaissent cote a cote. AGENT_FLOW_RUNTIME=claude ou AGENT_FLOW_RUNTIME=codex limite le mode autonome; le reglage VS Code agentVisualizer.runtime joue le meme role.
Pourquoi l’observabilite des agents compte
Un build echoue indique le resultat, pas la chaine de decisions. Un gros diff montre les changements, pas les trois pistes abandonnees avant de les produire.
Les traces visuelles aident a :
- Comprendre la decomposition. Voir comment une demande est devenue taches et delegations.
- Deboguer la causalite. Suivre la chaine exacte avant une mauvaise modification.
- Trouver le gaspillage. Reperer appels lents, relectures, branches redondantes et agents inactifs.
- Ameliorer les prompts. Comparer les formes d’execution et les instructions qui concentrent le travail.
Cette visibilite devient essentielle quand plusieurs agents travaillent en parallele.
Trois facons de lancer Agent Flow
Le chemin le plus rapide ne demande aucun clone :
npx agent-flow-app
L’application utilise le port 3001 par defaut. --port, --no-open et --verbose modifient son lancement.
Pour travailler depuis les sources :
git clone https://github.com/patoles/agent-flow.git
cd agent-flow
pnpm i
pnpm run setup
pnpm run dev
L’interface de developpement s’ouvre sur http://localhost:3000. Le depot demande Node.js 20+ et pnpm.
Dans l’editeur, installez l’extension puis executez Agent Flow: Open Agent Flow. Elle prend en charge les editeurs compatibles VS Code 1.85+ et configure automatiquement les hooks Claude Code a la premiere ouverture.
Workflow de debogage pratique
Commencez par une vraie tache : ouvrez Agent Flow, lancez un refactoring assez complexe et observez sans intervenir.
Apres execution :
- inspectez les noeuds les plus longs de la timeline
- ouvrez les appels inattendus et leurs resultats
- recherchez les fichiers ayant recu beaucoup d’attention
- comparez le travail parent aux branches deleguees
- verifiez si chaque branche a apporte une preuve ou duplique une autre
- reliez le comportement observe au prompt initial
Le nombre de noeuds n’est pas une metrique de qualite. Un grand graphe peut montrer un parallelisme sain; un petit peut cacher une hypothese couteuse. Formez une hypothese visuellement, puis validez-la avec la transcription et le code.
Confidentialite et telemetrie
Les traces d’agents peuvent contenir du contexte sensible. Selon le projet, la telemetrie anonyme est activee par defaut uniquement dans le binaire publie npx agent-flow-app, avec desactivation possible. Le developpement depuis les sources et l’extension VS Code n’envoient rien.
Le binaire publie collecte des donnees operationnelles agregees : nombre et duree des sessions, volume d’evenements, plateforme, version, identifiants de modeles observes, runtimes suivis et classes d’erreurs. Il n’envoie pas prompts, chemins de fichiers, contenu des appels d’outils, informations utilisateur ou variables d’environnement.
Definissez AGENT_FLOW_TELEMETRY=false ou DO_NOT_TRACK=1 pour la couper. Une equipe doit tout de meme verifier le schema actuel et ses propres exigences de gouvernance.
Ou Agent Flow est le plus utile
Agent Flow convient notamment :
- aux developpeurs qui apprennent comment les agents interpretent les prompts
- aux equipes qui deboguent une orchestration multi-agents
- aux mainteneurs qui evaluent l’utilisation des outils et le temps perdu
- aux demonstrations ou le terminal masque l’architecture
- aux revues basees sur des traces JSONL sauvegardees
Ce n’est pas un benchmark a lui seul. L’activite visuelle fournit des preuves, pas une note de qualite. Associez-la aux tests, a la revue de code, aux criteres de succes, aux couts et a la latence.
Conclusion
Les agents de codage deviennent des systemes plutot que de simples tours de chat. Lorsqu’ils se ramifient, deleguent et s’executent en parallele, les logs deviennent difficiles a lire.
Agent Flow donne un modele spatial a cette execution. Hooks Claude Code, parsing des rollouts Codex, sessions multiples, graphe, timeline, transcription et rejeu rendent l’orchestration inspectable sans remplacer les outils existants.
Le message est clair : de meilleurs agents ont besoin d’une meilleure observabilite. Voir le flux permet de deboguer le travail et d’ameliorer les instructions qui le guident.