extracting-session-data

Localise, liste, filtre et extrait des données structurées depuis les logs de session natifs de Claude Code. Prend en charge l'analyse de sessions individuelles ou multiples.

npx skills add https://github.com/bitwarden/ai-plugins --skill extracting-session-data

Compétence d'extraction de données de session

Responsabilité centrale

Fournir un accès brut aux journaux de session Claude Code stockés dans ~/.claude/projects/{project-dir}/{session-id}.jsonl.

Principe clé : Cette compétence extrait uniquement les données - retourner les données brutes aux compétences appelantes pour analyse. Ne pas analyser ou interpréter au sein de cette compétence.

Scripts disponibles

Tous les scripts sont situés dans le sous-répertoire scripts/ relatif à cette compétence.

1. locate-logs.sh

Trouver le répertoire de journaux ou le chemin d'accès à un fichier de session spécifique.

# Obtenir le répertoire de journaux pour le répertoire de travail actuel
scripts/locate-logs.sh

# Obtenir le répertoire de journaux pour un projet spécifique
scripts/locate-logs.sh /path/to/project

# Obtenir le chemin d'accès au fichier de journal de session spécifique
scripts/locate-logs.sh /path/to/project abc123-session-id

À utiliser quand : Construire des chemins dynamiques, vérifier l'existence des journaux avant le traitement.

2. list-sessions.sh

Énumérer toutes les sessions avec métadonnées (ID, taille, lignes, date, branche).

# Lister toutes les sessions (format tableau)
scripts/list-sessions.sh

# Sortie JSON
scripts/list-sessions.sh --format json

# Trier par taille ou lignes
scripts/list-sessions.sh --sort size
scripts/list-sessions.sh --sort lines

# Projet spécifique
scripts/list-sessions.sh /path/to/project

Formats de sortie : table, json, csv Options de tri : date, size, lines

À utiliser quand : Commencer une rétrospective, afficher les sessions disponibles à l'utilisateur, vérifier les sessions récentes.

3. extract-data.sh

Parser les journaux JSONL et extraire des types de données spécifiques.

Types d'extraction disponibles :

  • metadata - Infos de session (ID, horodatages, branche, répertoire de travail)
  • user-prompts - Tous les messages utilisateur
  • tool-usage - Statistiques d'appels d'outils
  • errors - Appels d'outils échoués avec horodatages
  • thinking - Blocs de réflexion (si la réflexion étendue est activée)
  • text-responses - Réponses texte de l'assistant uniquement
  • statistics - Métriques de session (compte de messages, appels d'outils, erreurs)
  • all - Extraction combinée
# Extraire d'une session spécifique
scripts/extract-data.sh --type statistics --session SESSION_ID
scripts/extract-data.sh --type errors --session SESSION_ID
scripts/extract-data.sh --type tool-usage --session SESSION_ID

# Extraire de toutes les sessions (omettre --session)
scripts/extract-data.sh --type statistics

# Limiter la sortie
scripts/extract-data.sh --type user-prompts --limit 10

# Projet différent
scripts/extract-data.sh --type metadata --project /path/to/project

À utiliser quand : Besoin de données spécifiques sans charger le journal complet, générer des métriques, identifier les erreurs.

4. filter-sessions.sh

Trouver les sessions correspondant aux critères.

Options de filtre :

  • --since DATE - Sessions modifiées depuis la date ("2 days ago", "2025-10-20")
  • --until DATE - Sessions modifiées jusqu'à la date
  • --branch NAME - Sessions sur une branche git spécifique
  • --min-size SIZE - Taille minimale du fichier ("1M", "500K")
  • --max-size SIZE - Taille maximale du fichier
  • --min-lines N - Nombre minimum de lignes
  • --max-lines N - Nombre maximum de lignes
  • --has-errors - Uniquement les sessions avec appels d'outils échoués
  • --keyword WORD - Sessions contenant le mot-clé

Formats de sortie : list, paths, json

# Sessions récentes
scripts/filter-sessions.sh --since "2 days ago"

# Grandes sessions avec erreurs
scripts/filter-sessions.sh --min-lines 500 --has-errors

# Sessions sur la branche main la semaine dernière
scripts/filter-sessions.sh --branch main --since "7 days ago"

# Sessions contenant le mot-clé
scripts/filter-sessions.sh --keyword "authentication"

# Obtenir uniquement les chemins (pour pipe)
scripts/filter-sessions.sh --since "1 day ago" --format paths

À utiliser quand : L'utilisateur demande l'analyse de sessions récentes, trouver des sessions pour une fonctionnalité/branche spécifique, identifier les sessions problématiques.

Processus de travail

Analyse d'une seule session

# 1. Vérifier que la session existe et obtenir les métadonnées
scripts/extract-data.sh --type metadata --session SESSION_ID

# 2. Obtenir les statistiques de session (pour déterminer la taille)
scripts/extract-data.sh --type statistics --session SESSION_ID

# 3. Extraire les données spécifiques selon les besoins
scripts/extract-data.sh --type errors --session SESSION_ID
scripts/extract-data.sh --type tool-usage --session SESSION_ID

Analyse de plusieurs sessions

# 1. Filtrer pour trouver les sessions pertinentes
scripts/filter-sessions.sh --since "7 days ago" --branch main

# 2. Extraire les données de toutes les sessions filtrées
scripts/extract-data.sh --type statistics

# 3. Ou itérer sur le sous-ensemble filtré
SESSIONS=$(scripts/filter-sessions.sh --has-errors --format paths)
for session in $SESSIONS; do
    SESSION_ID=$(basename "$session" .jsonl)
    scripts/extract-data.sh --type errors --session $SESSION_ID
done

Modèle d'intégration pour les compétences appelantes

Quand une autre compétence (comme la rétrospective) a besoin de données de session :

  1. Découverte : Utiliser list-sessions.sh ou filter-sessions.sh pour trouver les sessions pertinentes
  2. Vérification de la taille : Utiliser extract-data.sh --type statistics pour déterminer la complexité de la session
  3. Extraction ciblée : Utiliser extract-data.sh avec des types spécifiques pour les données nécessaires
  4. Retourner les données brutes : Retourner les données extraites à l'appelant pour analyse

Exemple :

# Obtenir l'ID de la session la plus récente
LATEST=$(scripts/list-sessions.sh --format json --sort date | jq -r '.[0].sessionId')

# Vérifier la taille avant le traitement
STATS=$(scripts/extract-data.sh --type statistics --session $LATEST)
LINE_COUNT=$(echo "$STATS" | grep "Total Lines:" | awk '{print $3}')

# Extraire en fonction de la taille
if [ "$LINE_COUNT" -lt 500 ]; then
    # Petite session : extraire les détails
    scripts/extract-data.sh --type errors --session $LATEST
    scripts/extract-data.sh --type tool-usage --session $LATEST
else
    # Grande session : résumé uniquement
    scripts/extract-data.sh --type statistics --session $LATEST
fi

Gestion du budget de contexte

CRITIQUE : Cette compétence est conçue pour l'efficacité de contexte

Utiliser le traitement Bash, pas l'outil Read

# BON : Extraire via bash, reste dans le contexte bash
STATS=$(scripts/extract-data.sh --type statistics)
# Traiter $STATS en bash

# MAUVAIS : Lire les fichiers journaux complets
Read ~/.claude/projects/-path/session.jsonl
# Charge le fichier entier dans le contexte inutilement

Vérifier la taille de la session avant le chargement

Ne jamais charger les journaux de session complets dans le contexte sans vérifier d'abord la taille.

# Toujours vérifier les statistiques en premier
scripts/extract-data.sh --type statistics --session SESSION_ID
# Affiche le nombre total de lignes, les comptes de messages, etc.

# Règles de décision :
# - Petit (<500 lignes) : Peut extraire les détails en toute sécurité
# - Moyen (500-2000 lignes) : Utiliser l'extraction sélective
# - Grand (>2000 lignes) : Statistiques uniquement, offrir des analyses approfondies ciblées

Retourner les données brutes à l'appelant

Cette compétence doit :

  • Exécuter des scripts bash pour extraire les données
  • Retourner la sortie texte brute à la compétence appelante
  • Laisser la compétence appelante gérer le contexte pour l'analyse
  • Éviter l'interprétation ou l'analyse au sein de cette compétence

Format de sortie

Retourner les données brutes extraites avec une mise en forme minimale :

# Sortie de statistiques
Session: abc123-def456-ghi789
  Total Lines: 450
  User Messages: 12
  Assistant Messages: 23
  Tool Calls: 45
  Errors: 2

# Sortie d'utilisation d'outils
=== Tool Usage: abc123-def456-ghi789 ===
Read                          15
Bash                          12
Edit                          8
Grep                          5
Write                         3

Pas d'analyse, pas d'interprétation - juste l'extraction de données.

Gestion des erreurs

Tous les scripts se terminent avec un statut non zéro en cas d'erreurs et produisent une sortie vers stderr.

Vérifier le statut de sortie avant le traitement :

if ! scripts/locate-logs.sh /path/to/project &>/dev/null; then
    # Gérer : le répertoire de journaux n'existe pas
    echo "Project has no session logs yet"
fi

if ! scripts/extract-data.sh --type metadata --session abc123 &>/dev/null; then
    # Gérer : la session n'existe pas
    echo "Session not found"
fi

Messages d'erreur courants :

  • Error: Logs directory not found: ~/.claude/projects/-path
  • Error: Session file not found: ~/.claude/projects/-path/session-id.jsonl
  • Error: --type is required
  • Error: jq is required but not installed. Install with: brew install jq

Calcul du chemin

Claude Code stocke les sessions avec ce modèle :

~/.claude/projects/{project-identifier}/{session-id}.jsonl

Où {project-identifier} est calculé en remplaçant tous les / par - dans le chemin du répertoire de travail absolu :

# Exemple : /Users/user/project → -Users-user-project
PROJECT_ID=$(echo "${PWD}" | sed 's/\//\-/g')
LOGS_DIR="${HOME}/.claude/projects/${PROJECT_ID}"

Tous les scripts utilisent locate-logs.sh en interne pour un calcul de chemin cohérent.

Anti-modèles à éviter

Ne pas :

  • Charger les journaux de session complets dans le contexte sans vérifier la taille
  • Parser JSONL manuellement - utiliser extract-data.sh
  • Coder en dur les chemins de journaux - utiliser locate-logs.sh
  • Analyser ou interpréter les données - retourner les données brutes à l'appelant
  • Traiter les grands journaux de manière synchrone sans sensibiliser l'utilisateur

Faire :

  • Vérifier la taille de la session avec --type statistics avant le traitement
  • Utiliser le type d'extraction approprié pour les besoins spécifiques
  • Filtrer les sessions avant l'extraction pour l'efficacité
  • Diffuser/canaliser les données lors du traitement de plusieurs sessions
  • Retourner les données brutes pour que l'appelant les analyse

Critères de réussite

L'utilisation efficace de cette compétence signifie :

  1. Découverte efficace : Trouver rapidement les sessions pertinentes sans recherche manuelle
  2. Extraction ciblée : Obtenir exactement les données nécessaires, rien de plus
  3. Préservation du contexte : Éviter de charger les données inutiles dans le contexte
  4. Accent sur les données brutes : Retourner les données non traitées pour que l'appelant les analyse
  5. Support multi-sessions : Gérer efficacement l'analyse sur plusieurs périodes ou branches

Dépendances

Requises :

  • bash (v4.0+)
  • jq (analyseur JSON)

Les scripts vérifient jq et fournissent des instructions d'installation si manquant :

Error: jq is required but not installed. Install with: brew install jq

Skills similaires

fix
facebook / react

244 800
flags
facebook / react

244 800
fix
facebook / react

244 800
perform-preflight
bitwarden / ai-plugins

89
bitwarden-workflow-linter-rules
bitwarden / ai-plugins

Auditer et corriger automatiquement les workflows GitHub Actions selon des règles strictes.

89