Agent Flow : rendre visible l'exécution d'un agent Claude Code

Ce que la réponse finale de Claude Code ne montre pas

Un agent Claude Code qui termine une tâche renvoie un résultat. Entre le prompt et ce résultat, il a choisi des outils, ouvert des fichiers, bifurqué, puis est revenu. Cette séquence n'apparaît nulle part dans la sortie. Le README d'Agent Flow part d'un constat d'auteur : le projet est né pendant le développement de CraftMyGame, une plateforme de création de jeux pilotée par des agents, parce que déboguer leur comportement était pénible. C'est un outil de diagnostic, pas de pilotage. Il ne modifie pas ce que fait l'agent, il enregistre ce qu'il fait. Le public visé est donc étroit : quelqu'un qui écrit des prompts ou des configurations d'outils, et qui doit comprendre pourquoi l'agent a pris un chemin inattendu. Pour un utilisateur qui se contente de lancer une tâche et de lire le résultat, le graphe n'apporte rien.

Deux sources d'événements, deux mécanismes distincts

Agent Flow ne lit pas dans les pensées de l'agent. Il s'accroche à deux flux. Pour Claude Code, le README décrit un serveur de hooks HTTP qui reçoit les événements directement, ce qui donne un streaming qualifié de zéro latence. Pour Codex, l'approche est différente : le projet lit les fichiers ~/.codex/sessions/**/rollout-*.jsonl, en respectant la variable CODEX_HOME, et en extrait les appels d'outils, le raisonnement et les compteurs de tokens que Codex produit lui-même. La distinction compte. Côté Claude Code, il faut installer quelque chose dans la configuration de l'agent. Côté Codex, il suffit de lire des fichiers déjà écrits sur le disque. Le même panneau peut afficher les deux en parallèle, chaque session étant étiquetée par runtime. Un troisième mode existe : pointer agentVisualizer.eventLogPath vers un fichier .jsonl quelconque, ce qui transforme l'outil en lecteur de journal plutôt qu'en observateur en direct.

Mise en route : trois chemins, pas un seul

Le chemin le plus court ne demande pas VS Code : npx agent-flow-app démarre le visualiseur dans le navigateur, avec --port pour changer le port (3001 par défaut), --no-open pour ne pas ouvrir le navigateur et --verbose pour les journaux détaillés. Il faut ensuite lancer une session Claude Code dans un autre terminal. Depuis les sources, la séquence est git clone, pnpm i, pnpm run setup, puis pnpm run dev, qui démarre le serveur Next.js et un relais d'événements diffusés au navigateur en SSE. pnpm run setup configure les hooks Claude Code, et le README précise qu'il s'agit d'une opération unique. Dans VS Code, l'extension installe ces mêmes hooks à la première ouverture du panneau, et la commande Agent Flow: Configure Claude Code Hooks permet de refaire l'opération à la main. Le raccourci Cmd+Alt+A ou Ctrl+Alt+A ouvre le panneau. Node.js 20+ et pnpm sont requis. Le réglage agentVisualizer.runtime accepte "auto", "claude" ou "codex", et l'équivalent en ligne de commande est la variable d'environnement AGENT_FLOW_RUNTIME.

Le graphe comme modèle, et ce qu'il coûte

Représenter une exécution d'agent sous forme de nœuds et d'arêtes est un choix, pas une évidence. Un agent qui enchaîne vingt appels d'outils produit un graphe large, et le README mentionne le pan, le zoom et le clic pour inspecter un nœud, ce qui suppose une lecture manuelle. Pour compenser, le projet ajoute une timeline, une heatmap d'attention sur les fichiers et un panneau de transcription. Ces vues secondaires sont probablement plus utiles que le graphe lui-même dès que la session dépasse quelques minutes, parce qu'une heatmap se lit d'un coup d'œil alors qu'un graphe se parcourt. Le README affirme qu'on repère ainsi les appels d'outils lents ou le travail redondant. C'est plausible pour un cas évident, mais aucune méthode de mesure n'est documentée : la lenteur perçue dépend de ce que l'interface affiche, pas d'un seuil calculé. À prendre comme une aide à l'intuition, pas comme un profilage.

Codex en lecture seule, Claude Code en écriture

Les deux intégrations n'ont pas le même profil de risque. Le suivi des rollout-*.jsonl de Codex est passif : Agent Flow lit des fichiers que Codex écrit de toute façon. La contrepartie est une dépendance à un format interne, non documenté comme stable, et le correctif listé en v0.9.0 sur la découverte de Codex montre que cette surface bouge. L'intégration Claude Code est active : pnpm run setup écrit des hooks dans la configuration de l'agent, et le correctif v0.9.1 porte sur la découverte de sessions sous Windows. Si votre configuration Claude Code est déjà personnalisée, cette écriture mérite un examen avant de lancer la commande. Le README ne décrit pas de commande de désinstallation des hooks. C'est une lacune réelle pour un outil qui modifie la configuration d'un autre outil.

Télémétrie activée par défaut, et la question de la licence

Le README indique que le binaire publié via npx agent-flow-app envoie une télémétrie anonyme d'usage, activée par défaut et désactivable. pnpm run dev et l'extension VS Code n'émettent rien selon le même document. La distinction est nette : si vous voulez zéro émission, passez par les sources ou par l'extension, pas par npx. Le texte fourni s'arrête au milieu de la phrase décrivant ce qui est envoyé, donc la nature exacte des événements agrégés ne peut pas être vérifiée ici. Le projet est publié sous Apache-2.0, une licence permissive qui autorise l'usage commercial et la modification, avec obligation de conserver les mentions de licence et d'indiquer les fichiers modifiés. Je ne donne pas d'avis juridique : pour un usage en entreprise, faites lire le fichier LICENSE et la politique de télémétrie par qui de droit.

Ce qu'un traceur OpenTelemetry ferait différemment

L'alternative directe n'est pas un autre visualiseur d'agents, c'est l'instrumentation générique. Un traceur de type OpenTelemetry place des spans autour des appels d'outils et les exporte vers un backend d'observabilité. La différence de conception est nette : Agent Flow déduit sa structure en s'accrochant aux hooks de Claude Code et au format rollout de Codex, ce qui le rend immédiatement utilisable mais le lie à ces deux runtimes et à leurs formats internes. Une instrumentation explicite demande d'écrire du code dans l'agent, mais reste indépendante du fournisseur et s'intègre aux alertes et aux requêtes d'un backend existant. Le choix se joue donc entre zéro effort d'intégration avec une portée limitée à deux runtimes, et un effort d'instrumentation avec une portée que vous contrôlez. Pour un agent maison qui n'est ni Claude Code ni Codex, Agent Flow n'a rien à observer, sauf si vous produisez vous-même un fichier .jsonl au format attendu.

Conclusion éditoriale

Agent Flow convient aux développeurs qui utilisent déjà Claude Code ou Codex en CLI et qui veulent voir la séquence réelle des appels d'outils plutôt que la réponse finale. Ceux qui cherchent un outil agnostique, ou qui refusent la télémétrie anonyme activée par défaut dans le binaire npx, doivent passer leur chemin. Avant d'adopter, vérifiez que pnpm run setup a bien écrit les hooks dans votre configuration Claude Code et que le panneau reçoit des événements sur une session réelle.

Sources officielles

1. License: Apache-2.0
2. patoles/agent-flow on GitHub
3. Project website
4. README
5. Releases