Voir ses agents IA travailler en direct avec VFG Agent Presence

Installer une page locale qui affiche Codex, Claude Code, Cursor, Kimi et Ollama sous forme de carrés d'activité, sans conserver les prompts complets.

Quand plusieurs agents travaillent en parallèle, le problème n’est plus seulement de leur donner une tâche. Il faut savoir qui travaille, sur quoi, depuis combien de temps et dans quel dépôt. Une collision silencieuse — deux agents dans le même répertoire — peut produire des modifications impossibles à attribuer ou à fusionner.

VFG Agent Presence ajoute une vue locale simple : chaque tour d’agent devient un carré coloré dans Chronowflow. La télémétrie est déclenchée par les hooks natifs des clients, pas par la bonne volonté du modèle. Elle reste non bloquante : si l’observabilité tombe, le prompt continue normalement.

Ce qui est installé

La chaîne locale est la suivante :

Codex / Claude Code / Cursor / Kimi
              │ hooks natifs
              ▼
        VFGate :5191
              │ relais 500 ms
              ▼
       FG_Chronos :4340
              │ API de lecture
              ▼
       Chronowflow :4477

Ollama peut passer par ai-usage-hub :

Client Ollama → ai-usage-hub :11435 → Ollama :11434
                         └──────→ VFGate

Les responsabilités restent séparées :

VFGate reçoit et journalise les événements.
FG_Chronos conserve le ledger temporel et reconstruit les sessions actives.
Chronowflow affiche les carrés et le fil chronologique.
ai-usage-hub mesure les requêtes Ollama, leur durée et leurs tokens.

Tout écoute sur 127.0.0.1. Aucun service n’est publié sur le réseau local ou Internet par défaut.

Prérequis

Sur Windows, il faut :

PowerShell 5.1 ou supérieur ;
Node.js 20 ou supérieur ;
Git ;
les dépôts VFGate, FG_Chronos et Chronowflow disponibles localement ;
Ollama uniquement si l’on veut observer des modèles locaux.

Vérification rapide :

node --version
git --version
$PSVersionTable.PSVersion

Installation automatique

Ouvrir PowerShell dans le dépôt FG_Chronos, puis lancer :

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-agent-presence.ps1

Le programme :

sauvegarde les configurations existantes dans %LOCALAPPDATA%\VFG\agent-presence\backups ;
fusionne les hooks sans remplacer les hooks tiers ;
installe le skill canonique vfg-agent-presence ;
ajoute la règle permanente de Cursor ;
ajoute les instructions globales de Codex et Claude Code ;
configure Kimi CLI ;
crée la tâche Windows VFG-Agent-Presence au démarrage de session.

La commande est idempotente : on peut la rejouer après une mise à jour sans multiplier les hooks.

Pour simuler l’installation sans écrire :

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-agent-presence.ps1 -WhatIf

Démarrer la pile

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\start-agent-presence.ps1

Le script démarre seulement les processus absents, attend leurs healthchecks puis ouvre Chronowflow :

http://127.0.0.1:4477

Pour démarrer sans ouvrir le navigateur :

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\start-agent-presence.ps1 -NoOpen

Vérifier l’installation

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\doctor-agent-presence.ps1

Le diagnostic contrôle les ports, healthchecks, fichiers de hooks, proxy Ollama et tâche planifiée. Il indique seulement si les éléments requis sont présents ; il n’affiche jamais les tokens.

Les services attendus sont :

Service	Adresse locale
VFGate	`http://127.0.0.1:5191`
FG_Chronos	`http://127.0.0.1:4340`
Chronowflow	`http://127.0.0.1:4477`
Ollama	`http://127.0.0.1:11434`
Proxy Ollama	`http://127.0.0.1:11435`

Premier test avec Codex dans VS Code

Codex demande une validation explicite des hooks locaux. Après installation :

redémarrer la session Codex ou recharger VS Code ;
exécuter /hooks dans Codex ;
examiner et approuver les commandes emit-agent-event.mjs ;
envoyer un nouveau prompt ;
ouvrir Chronowflow.

Le carré doit apparaître en moins de deux secondes. Un appel d’outil met à jour l’activité ; l’arrêt du tour le fait passer à l’état terminé.

Claude Code

L’installateur fusionne les événements suivants dans ~/.claude/settings.json : début du prompt, utilisation ou échec d’outil, arrêt, interruption, échec et cycle de vie des sous-agents.

Après installation, fermer puis rouvrir Claude Code et envoyer un prompt. Le client affiché dans Chronowflow doit être claude-code.

Claude Desktop n’est pas Claude Code. L’application Desktop ne fournit pas les mêmes hooks de cycle de vie. Ajouter un serveur MCP à Claude Desktop permettrait au modèle d’appeler un outil, mais ne garantirait pas un événement à chaque prompt. La garantie technique décrite ici concerne donc Claude Code.

Cursor

Cursor reçoit ses hooks dans ~/.cursor/hooks.json et une règle alwaysApply dans :

~/.cursor/rules/vfg-agent-presence.mdc

Rechargez la fenêtre Cursor après installation. Les hooks existants sont conservés. beforeSubmitPrompt crée la session ; les événements d’outil alimentent la progression ; stop ou sessionEnd ferment le tour.

Kimi CLI

L’installateur ajoute un bloc délimité à ~/.kimi-code/config.toml, installe le skill et configure notamment le heartbeat de session. Redémarrer Kimi CLI suffit à charger la configuration.

Le bloc est marqué BEGIN/END VFG AGENT PRESENCE, ce qui permet une désinstallation ciblée sans toucher aux autres réglages.

Ollama via le proxy

L’instance Ollama réelle reste sur 11434. Les clients que l’on souhaite mesurer doivent appeler le proxy 11435 :

$env:OLLAMA_HOST = "http://127.0.0.1:11435"
ollama list

Selon le client, configurer son URL Ollama sur http://127.0.0.1:11435. Le proxy publie le modèle, la durée et les compteurs de tokens. Il ne publie pas les messages envoyés au modèle.

Une requête Ollama directe, sans hook d’agent, peut être enregistrée avec un répertoire inconnu. Les fournisseurs cloud de Codex, Claude ou Kimi ne sont pas forcés à travers ce proxy : leurs hooks restent la source de présence.

Comprendre les couleurs

Vert pulsé : tour actif avec activité récente.
Ambre : tour encore déclaré actif, mais dont la dernière activité devient ancienne.
Gris : tour terminé ; il disparaît ensuite de la vue active.
Rouge : interruption ou échec.
Contour rouge : plusieurs sessions actives partagent le même dépôt normalisé.

Un clic sur un carré sélectionne la session et son fil chronologique. Après rechargement de la page, l’état est reconstruit depuis Chronos ; il ne dépend pas de localStorage.

Une tâche, un worktree

La télémétrie signale les collisions mais ne bloque jamais le prompt. La bonne pratique reste d’isoler chaque tâche :

git fetch
git worktree add ..\mon-projet-tache-123 -b agent/tache-123
Set-Location ..\mon-projet-tache-123

Chaque agent reçoit un worktree, une tâche et un handoff. Avant de modifier un fichier, il doit lire les instructions du dépôt, git status, les derniers commits et le handoff actif.

Un handoff minimal contient :

- Tâche :
- Dépôt ou worktree exclusif :
- État :
- Fichiers touchés :
- Tests exécutés :
- Risques ou échecs connus :
- Prochaine action exacte :

Confidentialité

Le prompt brut ne quitte jamais le processus du hook. Seul un aperçu nettoyé de 120 caractères maximum est produit. Les retours à la ligne sont supprimés et les motifs courants de tokens, clés API, mots de passe et secrets sont masqués.

Ne placez malgré tout jamais de token, URL signée, mot de passe ou donnée personnelle dans le titre d’une tâche. La télémétrie doit rester une aide opérationnelle, pas une copie des conversations.

Si aucun carré n’apparaît

Procéder dans cet ordre :

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\doctor-agent-presence.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\start-agent-presence.ps1 -NoOpen

Puis vérifier :

que le client a été redémarré après installation ;
que Codex a approuvé les hooks via /hooks ;
que http://127.0.0.1:4477 répond ;
que VFGate contient un événement récent ;
que Chronos retourne des sessions actives.

Endpoints de diagnostic :

GET http://127.0.0.1:5191/api/vfgate/v1/events/tail?limit=20
GET http://127.0.0.1:4340/v1/query/agents/active
GET http://127.0.0.1:4340/v1/events?kind=agent.turn&limit=20
GET http://127.0.0.1:4477/api/chronos

Les logs locaux sont sous %LOCALAPPDATA%\VFG\agent-presence\logs. La file de secours est spool.jsonl dans le même espace de données. Si VFGate est indisponible, le hook écrit dans cette file puis rend immédiatement la main ; le forwarder rejoue les événements plus tard avec leurs identifiants d’origine pour éviter les doublons.

Désinstallation

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\uninstall-agent-presence.ps1

Cette commande retire uniquement les hooks, règles, skills et la tâche planifiée gérés par VFG Agent Presence. Les données Chronos sont conservées.

Pour restaurer les configurations de référence sauvegardées avant la première installation :

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\uninstall-agent-presence.ps1 -RestoreLatestBackup

Pour aller plus loin

La prochaine évolution naturelle est un résumé dans VFG Cockpit, sans remplacer la vue détaillée Chronowflow. Une migration vers un VPS ou Tailscale pourra ensuite conserver exactement le même contrat d’événement : seules les URL et l’authentification changeront.

Le principe essentiel restera le même : les hooks décrivent le cycle de vie, VFGate transporte, Chronos se souvient et Chronowflow rend le travail visible.