Plugin Claude Code

Le plugin CoreWeave Forge pour Claude Code trace automatiquement chaque session Claude Code et envoie les données structurées à Agent Lens. Il journalise chaque tour de conversation, chaque appel d’outil et chaque sous-agent, sans aucune modification de code. Servez-vous de ces traces pour déboguer les sessions, auditer l’utilisation des outils et surveiller le coût et la latence d’un run à l’autre. Ce guide vous explique comment installer le plugin, afficher vos traces Claude Code dans Agent Lens, configurer le plugin et gérer son cycle de vie.

Ce plugin envoie les données de session Claude Code à Agent Lens. Ces données peuvent inclure les prompts utilisateur, les réponses de Claude, les entrées et sorties des outils, le contenu des fichiers lus par les outils de Claude Code, les commandes shell et leur sortie, ainsi que les URL récupérées et le contenu des pages.Le nettoyage des données personnelles (PII) et le masquage des données sensibles ne sont pas implémentés. Si vos exigences de sécurité ou de conformité ne vous permettent pas d’envoyer ces données à Agent Lens, n’installez pas ce plugin.

Prérequis

Node.js v18.19 ou version ultérieure, ou v20.6 ou ultérieure (npm inclus).
Claude Code installé et authentifié.
Un compte CoreWeave Forge et une clé API définie dans la variable d’environnement WANDB_API_KEY.
Un projet Agent Lens ([YOUR-TEAM]/[YOUR-PROJECT]) destiné à recevoir les traces.

Installer le plugin

Installez la CLI, exécutez le programme d’installation pour enregistrer le plugin auprès de Claude Code, puis démarrez une session Claude Code pour lancer le traçage.

Installer la CLI

Ce plugin est distinct du plugin weave-claude-code décrit dans le guide Weave. Sa CLI s’appelle forge-agent-lens-for-claude-code, et ses compétences utilisent le nom forge. Si vous avez installé weave-claude-code ou l’ancien paquet @coreweave/forge-claude-code, désinstallez-le avant d’installer ce plugin, afin d’éviter que les deux n’envoient des traces en double :

# Si vous avez installé weave-claude-code :
weave-claude-code uninstall
npm uninstall -g weave-claude-code

# Si vous avez installé @coreweave/forge-claude-code :
forge-claude-code uninstall
npm uninstall -g @coreweave/forge-claude-code

Les paramètres de ces paquets ne sont pas repris. Définissez de nouveau votre projet et votre clé API lorsque le programme d’installation vous les demande. Si vous aviez défini les variables d’environnement du plugin, renommez WEAVE_PROJECT en FORGE_TRACE_PROJECT et WEAVE_AGENT_NAME en FORGE_CLAUDE_CODE_AGENT_NAME.

npm install -g @coreweave/forge-agent-lens-for-claude-code

Exécuter le programme d’installation

forge-agent-lens-for-claude-code install

Le programme d’installation effectue les opérations suivantes :

Il crée ~/.forge-agent-lens-for-claude-code/settings.json.
Il enregistre le plugin dans Claude Code.
Il vous demande votre projet Agent Lens ([YOUR-TEAM]/[YOUR-PROJECT]) et votre clé API Forge, s’ils ne sont pas encore définis.

Pour éviter les invites dans un environnement CI, des scripts d’amorçage ou d’autres systèmes automatisés, définissez les variables d’environnement avant l’exécution :

FORGE_TRACE_PROJECT=[YOUR-TEAM]/[YOUR-PROJECT] \
WANDB_API_KEY=[YOUR-API-KEY] \
forge-agent-lens-for-claude-code install --non-interactive

En mode non interactif, le programme d’installation crée quand même le fichier de configuration et enregistre le plugin. Il lit FORGE_TRACE_PROJECT et WANDB_API_KEY dans l’environnement et affiche un avertissement si l’une de ces variables est absente. Il n’écrit pas ces valeurs dans settings.json.Par défaut, le programme d’installation enregistre le plugin depuis GitHub. Si votre système CI ou votre conteneur ne peut pas accéder à GitHub, passez --source=local pour enregistrer le plugin à partir du paquet npm installé à l’étape précédente :

forge-agent-lens-for-claude-code install --non-interactive --source=local

Démarrer Claude Code

claude

Si Claude Code est déjà en cours d’exécution, exécutez plutôt /reload-plugins dans la session.Dès lors, le plugin trace automatiquement les sessions. Il trace toutes les sessions Claude Code de cette machine, et pas uniquement celles d’un projet donné.

Afficher les traces Claude Code dans Agent Lens

Après avoir exécuté au moins une session Claude Code, ouvrez votre projet dans l’interface d’Agent Lens :

Accédez à CoreWeave Forge, sélectionnez Agent Lens dans le menu des produits, puis sélectionnez votre projet dans le sélecteur de projet, en haut du menu latéral.
Dans le menu latéral, sélectionnez Conversations.
Sélectionnez l’onglet Conversations pour afficher toutes les conversations d’agents enregistrées dans votre projet.
Sélectionnez une conversation pour examiner son arborescence complète.

Pour plus d’informations sur l’onglet Conversation, consultez Afficher l’activité des agents. Chaque prompt utilisateur génère une trace OTEL conforme aux conventions sémantiques GenAI. La trace présente la hiérarchie complète des tours de conversation :

invoke_agent claude-code               (Racine, une trace par prompt utilisateur.)
├─ chat <model>                        (Chaque appel LLM du tour de conversation.)
├─ execute_tool <tool_name>            (Chaque appel d’outil, comme Read, Bash ou Grep.)
└─ invoke_agent <subagent_type>        (Sous-agent lancé via l’outil Agent.)
   ├─ chat <model>
   └─ execute_tool <tool_name>

Le span racine invoke_agent claude-code utilise le nom de l’agent de premier niveau, qui est par défaut claude-code. Vous pouvez le modifier avec le paramètre agent_name ou la variable d’environnement FORGE_CLAUDE_CODE_AGENT_NAME (voir Configurer le plugin). Les sous-agents conservent leurs propres noms de type. Les conversations sur plusieurs tours de conversation sont liées côté serveur par leur ID de conversation, ce qui vous permet de suivre une conversation à travers plusieurs traces. Chaque span inclut l’utilisation des jetons, le nom du modèle, les entrées et sorties des outils, les durées d’exécution, ainsi que le contenu textuel des prompts et des réponses. Pour en savoir plus sur les données tracées, consultez What Gets Traced sur GitHub.

Configurer le plugin

Après l’installation, utilisez les commandes forge-agent-lens-for-claude-code config pour afficher ou modifier les paramètres du plugin :

# Afficher tous les paramètres actuels.
forge-agent-lens-for-claude-code config show

# Afficher un paramètre, y compris sa valeur éventuellement redéfinie par une variable d’environnement.
forge-agent-lens-for-claude-code config get project

# Définir votre projet Agent Lens.
forge-agent-lens-for-claude-code config set project [YOUR-TEAM]/[YOUR-PROJECT]

# Définir votre clé API Forge.
forge-agent-lens-for-claude-code config set wandb_api_key [YOUR-API-KEY]

# (Facultatif) Personnaliser le nom de l’agent affiché dans l’onglet Conversations.
forge-agent-lens-for-claude-code config set agent_name [YOUR-AGENT-NAME]

Par défaut, les conversations apparaissent sous le nom d’agent claude-code dans l’onglet Conversations. Définissez agent_name pour utiliser un autre nom, par exemple pour distinguer des équipes ou des projets. Le nom ne peut pas être vide, et les espaces en début et en fin de chaîne sont supprimés. Le démon d’arrière-plan du plugin lit ses paramètres au démarrage. Pour appliquer un paramètre modifié à un démon en cours d’exécution, redémarrez-le :

forge-agent-lens-for-claude-code restart

Les variables d’environnement sont prioritaires sur le fichier de paramètres :

export FORGE_TRACE_PROJECT=[YOUR-TEAM]/[YOUR-PROJECT]
export WANDB_API_KEY=[YOUR-API-KEY]
export FORGE_CLAUDE_CODE_AGENT_NAME=[YOUR-AGENT-NAME]

Compétences Agent Lens

Une fois l’installation terminée, trois compétences propres à Agent Lens sont disponibles directement dans n’importe quelle session Claude Code.

Compétence	Commande	Description
Install	`/forge:forge-install`	Vous guide de manière interactive tout au long du processus d’installation et de configuration. Utilisez-le sur une nouvelle machine ou pour diagnostiquer une configuration défaillante.
Status	`/forge:forge-status`	Vérifie le statut actuel du plugin et explique les éventuels problèmes. Équivaut à exécuter `forge-agent-lens-for-claude-code status`, mais Claude interprète la sortie et vous indique ce qu’il faut corriger.
Config	`/forge:forge-config`	Lire ou mettre à jour la configuration du plugin sans quitter Claude Code.

Vous pouvez utiliser la compétence forge:forge-config pour définir des valeurs Agent Lens directement depuis Claude Code :

/forge:forge-config set project [YOUR-TEAM]/[YOUR-PROJECT]
/forge:forge-config set wandb_api_key [YOUR-API-KEY]
/forge:forge-config set agent_name [YOUR-AGENT-NAME]

Vérifier le statut du plugin

Vous pouvez utiliser ces commandes CLI pour vérifier le statut du plugin ou résoudre d’éventuels problèmes :

forge-agent-lens-for-claude-code status

Chaque ligne affiche ✓ (OK), ✗ (action requise) ou - (pas encore actif, sans que ce soit une erreur). Si les conversations n’apparaissent pas dans Agent Lens, exécutez la commande suivante pour afficher les 50 dernières lignes du journal du démon :

forge-agent-lens-for-claude-code logs

Pour afficher davantage de lignes, utilisez l’option --tail suivie du nombre de lignes souhaité :

forge-agent-lens-for-claude-code logs --tail 200

Pour suivre le journal en temps réel :

forge-agent-lens-for-claude-code logs --follow

Le fichier journal est également disponible à l’emplacement ~/.forge-agent-lens-for-claude-code/logs/daemon.log. Pour obtenir une sortie plus détaillée du démon pendant que vous diagnostiquez un problème, activez le mode débogage :

forge-agent-lens-for-claude-code config set debug true

Pour activer le mode débogage uniquement pour la session shell en cours, définissez plutôt FORGE_CLAUDE_CODE_DEBUG=1.

Désinstallation

Pour supprimer le plugin de Claude Code et arrêter le traçage, exécutez la commande suivante :

forge-agent-lens-for-claude-code uninstall

Ajoutez l’option --keep-logs pour conserver le répertoire des journaux.

Agent Lens

Guides

Intégrations

Référence

Prérequis

Installer le plugin

Afficher les traces Claude Code dans Agent Lens

Configurer le plugin

Compétences Agent Lens

Vérifier le statut du plugin

Désinstallation

​Prérequis

​Installer le plugin

​Afficher les traces Claude Code dans Agent Lens

​Configurer le plugin

​Compétences Agent Lens

​Vérifier le statut du plugin

​Désinstallation

Prérequis

Installer le plugin

Afficher les traces Claude Code dans Agent Lens

Configurer le plugin

Compétences Agent Lens

Vérifier le statut du plugin

Désinstallation