janole/session-bandit

Prérequis

Session Bandit est un outil CLI qui doit être installé sur le système. Vérifiez sa disponibilité :

command -v session-bandit

S'il n'est pas installé, installez-le globalement :

npm install -g session-bandit

Si le package n'est pas encore sur npm, installez-le depuis la source :

git clone https://github.com/janole/session-bandit.git
cd session-bandit
pnpm install
pnpm -r build
npm install -g packages/cli

Nécessite Node.js 22+ et pnpm 10+ (uniquement pour la construction depuis la source ; l'installation npm ne nécessite que Node.js).

Vérifiez l'installation :

session-bandit --version

Ce que fait Session Bandit

Session Bandit indexe les transcriptions de sessions que les agents de codage (Claude Code, Codex, BotBandit) écrivent sur le disque au format JSONL. Il fonctionne entièrement hors ligne — aucun appel API, aucune authentification, aucun réseau. Il analyse par défaut les répertoires ~/.claude/projects/, ~/.codex/sessions/ et ~/.botbandit/sessions/.

Modes de sortie

Privilégiez la sortie par défaut, lisible par machine, lorsque vous utilisez Session Bandit comme outil d'agent :

• list et search affichent des lignes JSON par défaut.
• extract, redact-check et doctor affichent du JSON par défaut.
• show affiche une transcription lisible par un humain.

Utilisez --pretty uniquement lorsqu'une vue terminale lisible par un humain est utile pour la navigation ou le rapport à l'utilisateur. N'ajoutez pas --pretty aux commandes dont vous prévoyez d'analyser la sortie ou de l'utiliser comme entrée structurée pour une note de passation ou une note mémoire.

Commandes

Lister les sessions

# Lister toutes les sessions, les plus récentes en premier (lignes JSON)
session-bandit list

# Tableau lisible avec niveau d'importance
session-bandit list --pretty

# Filtrer par agent ou projet
session-bandit list --agent codex --project botbandit

# Trier par substance/importance (sessions lourdes en premier)
session-bandit list --sort importance

# Ignorer les sessions triviales
session-bandit list --min-importance moderate

# Limiter à une période : relative (7d, 24h, 2w, 3m) ou date absolue
session-bandit list --since 7d
session-bandit list --since 2026-06-01 --until 2026-06-15

Afficher une transcription de session

# ID complet ou correspondance par préfixe
session-bandit show 342647fa-5bf
session-bandit show 342647fa --agent claude

Rechercher dans les sessions

session-bandit search "approbation d'outil"
session-bandit search "apply_patch" --agent codex
session-bandit search "adaptateur" --since 3d --pretty

Extraire un digest de session (la fonctionnalité clé pour les passations/mémoires)

# Digest structuré (JSON) — score de substance, fichiers, commandes, erreurs, échanges clés
session-bandit extract 342647fa-5bf

# Envelopper le digest dans une invite de synthèse prête à être envoyée
session-bandit extract 342647fa-5bf --prompt handoff
session-bandit extract 342647fa-5bf --prompt memory

# Inclure la transcription complète dans le digest
session-bandit extract 342647fa-5bf --full --prompt handoff

Vérifier l'état d'analyse syntaxique

session-bandit doctor
session-bandit doctor --agent codex
session-bandit doctor --agent botbandit

Vérifier la suppression d'informations sensibles avant publication

# Rapport JSON par défaut
session-bandit redact-check 342647fa-5bf

# Rapport lisible pour examen avec l'utilisateur
session-bandit redact-check 342647fa-5bf --pretty

# Aperçu plus conservateur
session-bandit redact-check 342647fa-5bf --redact strict

Exporter en Markdown pour révision/publication

session-bandit export-md 342647fa-5bf --out ./session.md
session-bandit export-md 342647fa-5bf --out ./session.md --report-out ./redaction-report.json
session-bandit export-md 342647fa-5bf --out ./session.md --title "Interface Apple Watch"

export-md utilise par défaut --redact cautious. N'utilisez pas --redact none pour un artefact public sauf si l'utilisateur le demande explicitement et en accepte le risque ; la CLI exige --yes pour ce mode.

Publier une session

Lorsqu'on vous demande de publier une session de codage, gardez Session Bandit déterministe et hors ligne. Utilisez la CLI pour créer l'artefact Markdown purgé et le rapport de purge ; utilisez votre jugement d'agent uniquement pour la sélection de la session, le choix du titre/slug, un éventuel polissage de la prose et le signalement du risque à l'utilisateur.

1. Trouvez la session source. Si l'utilisateur fournit un ID de session, utilisez-le directement. Sinon, recherchez ou listez les sessions probables :

   session-bandit list --sort importance
   session-bandit search "le sujet"
   

   Utilisez --agent ou --project lorsque l'utilisateur restreint la cible.

2. Choisissez le titre, le slug et les chemins de sortie. Pour un dépôt de type GitHub Pages, préférez un dossier par session :

   sessions/<slug>/index.md
   sessions/<slug>/redaction-report.json
   

   Gardez les slugs courts, en minuscules et stables. Si le titre est incertain, proposez-le à l'utilisateur avant d'exporter.

3. Prévisualisez la purge avant d'écrire l'artefact :

   session-bandit redact-check <sessionId> --pretty
   

   Signalez les comptes et tout risque notable. Utilisez --redact strict si la session semble contenir des données client privées, des identifiants, des résultats propriétaires ou un contexte local inhabituellement sensible.

4. Exportez le Markdown et le rapport :

   session-bandit export-md <sessionId> \
     --out sessions/<slug>/index.md \
     --report-out sessions/<slug>/redaction-report.json \
     --title "Titre lisible"
   

   N'utilisez pas --redact none pour une publication publique sauf si l'utilisateur le demande explicitement et en accepte le risque.

5. Révisez avant publication. Inspectez le Markdown et le rapport de purge. Assurez-vous que les sections de résumé, les sessions connexes, les commandes, les résultats d'outils et les chemins locaux sont raisonnables. La purge automatisée est un effort au mieux, pas une preuve de sécurité.

6. Optionnellement, peaufinez le Markdown. Vous pouvez ajouter ou modifier une courte introduction, des titres de section ou une note de conclusion en dehors de la sortie de la CLI. N'inventez pas de faits ; conservez intacts la transcription, le digest, la provenance et le rapport de purge.

7. Demandez avant de rendre public. Avant git add, git commit, git push ou toute action de déploiement, résumez le risque de purge et demandez l'approbation explicite de l'utilisateur, sauf s'il a déjà donné cette approbation dans le tour actuel.

Modèle GitHub Pages

Cette compétence est livrée avec un modèle de publication par défaut dans templates/github-pages-default/ à côté de ce SKILL.md. Utilisez-le lorsque l'utilisateur demande un dépôt GitHub Pages, un site statique peaufiné ou une présentation publique par défaut pour les sessions exportées.

Comportement du modèle :

• C'est un site Jekyll/GitHub Pages avec des mises en page et CSS personnalisés.
• Il attend les sessions générées dans sessions/<slug>/index.md.
• Il attend les rapports de purge à côté des sessions sous sessions/<slug>/redaction-report.json.
• Il utilise les valeurs par défaut de _config.yml afin que le Markdown exporté par Session Bandit reçoive automatiquement la mise en page de session.
• Il inclut un fixture local .design/session-page.html pour les vérifications de mise en page sans Jekyll ni déploiement Pages.
• Il est statique et autonome ; n'ajoutez pas de ressources externes, de traqueurs, de polices ou de scripts distants sauf demande explicite de l'utilisateur.

Lors de l'initialisation d'un dépôt de publication vide :

cp -R <répertoire-de-la-compétence>/templates/github-pages-default/. <dépôt-cible>/

Lorsque le dépôt existe déjà, ne remplacez pas _config.yml, _layouts/, assets/session.css, index.md ou README.md sans demander. Ajoutez ou mettez à jour uniquement sessions/<slug>/index.md, sessions/<slug>/redaction-report.json et une entrée d'index si l'utilisateur souhaite un index manuel.

Pour les modifications visuelles du modèle, préférez vérifier localement templates/github-pages-default/.design/session-page.html avant de publier. Il est intentionnellement construit en HTML simple, donc il ne nécessite pas Jekyll.

Rédiger une note de passation

Lorsqu'on vous demande de rédiger une note de passation à partir d'une session précédente :

1. Trouvez la session. Si l'utilisateur fournit un ID de session, utilisez-le directement. Sinon, listez les sessions récentes et choisissez celle qui convient :

   session-bandit list --sort importance
   

   Ou recherchez un sujet :

   session-bandit search "le sujet"
   

   Ajoutez --pretty uniquement si vous avez besoin d'un tableau/extrait pour une navigation manuelle.

2. Générez le digest avec une invite de passation :

   session-bandit extract <sessionId> --prompt handoff
   

   Cela émet un digest structuré (score de substance, fichiers écrits, erreurs, résumés/récapitulations, objectif, état final) enveloppé dans une invite de synthèse qui vous indique quoi écrire.

3. Rédigez la note de passation. L'invite vous demande de couvrir : l'objectif, ce qui a été fait, l'état actuel et ce qu'il reste à faire. Utilisez les données structurées du digest (fichiers écrits, erreurs, échanges clés) comme base factuelle. Restez concis — un agent de retour a besoin de l'état, pas de l'historique complet.

4. Enregistrez la note de passation là où l'utilisateur le souhaite (stockage de documents, fichier Markdown, etc.).

Rédiger une note mémoire

Lorsqu'on vous demande de créer une note mémoire à partir d'une session passée :

1. Trouvez et extrayez la session :

   session-bandit extract <sessionId> --prompt memory
   

2. Rédigez la note mémoire. L'invite demande 2 à 4 phrases couvrant : le sujet de la session, le résultat clé et les fichiers/décisions qui méritent d'être retenus. Terminez par un niveau d'importance suggéré (trivial / light / moderate / substantive / heavy).

3. Enregistrez la note mémoire là où l'utilisateur le souhaite.

Conseils

• Les modèles --prompt handoff et --prompt memory sont des premières ébauches. N'hésitez pas à adapter le format de sortie aux besoins de l'utilisateur — les données du digest sont la partie précieuse, pas le texte du modèle.
• Utilisez --full lorsque vous avez besoin de la transcription complète pour le contexte (par exemple, un travail complexe en plusieurs étapes). Sans --full, le digest est compact et peut omettre des détails.
• Les récapitulatifs Claude, les compactions Codex et les événements mémoire/compaction BotBandit sont présentés comme des messages summary et inclus dans les extraits. Traitez-les comme un contexte de synthèse utile, mais basez toujours les passations et les mémoires sur les fichiers, erreurs, tests et derniers échanges du digest.
• Avant d'aider à publier ou exporter une session publiquement, exécutez session-bandit redact-check <sessionId> --pretty et signalez le risque restant. La purge automatisée est un effort au mieux, pas une preuve de sécurité.
• Pour une exportation Markdown, privilégiez session-bandit export-md <sessionId> --out <chemin> --report-out <cheminRapport>, puis inspectez le rapport avant de suggérer un commit/publication.
• Le Markdown est l'artefact de publication canonique. Ne créez pas de transcription HTML basique sauf si l'utilisateur le demande spécifiquement ; un HTML de qualité doit être généré à partir du Markdown révisé ou du bundle purgé.
• Privilégiez le modèle fourni templates/github-pages-default/ pour les nouveaux dépôts de publication GitHub Pages. C'est la présentation publique par défaut sauf si l'utilisateur demande un autre style.
• Le score de substance mesure l'activité (appels d'outils, écritures de fichiers, exécutions de tests), pas l'importance. Une session courte peut contenir une décision critique. Lisez les échanges clés, pas seulement le score.
• Les ID de session peuvent être spécifiés comme préfixes (par exemple 342647fa au lieu de l'UUID complet).
• Exécutez session-bandit doctor si quelque chose semble anormal — il vérifie si les hypothèses d'analyse correspondent à vos fichiers de session réels, y compris les dérives de format, les marqueurs d'injection, les types non reconnus et les sauts silencieux. Utilisez --agent claude, --agent codex ou --agent botbandit pour restreindre la vérification.