← RetourCréé le 5 mai 2026

compact-manager

Skill

Gestion sémantique du contexte pour Claude Code — compresse les conversations longues, maintient la continuité cross-session, et apprend tes préférences de filtrage au fil du temps.

GitHub ↗README (FR) ↗

commandes

signaux hook

types de lessons

≤1500

tokens / snapshot

65%

seuil auto-compact

SommairePrésentation Architecture Installation Commandes Signaux Filtrage Lessons Snapshot Config Dépannage Fichiers

Présentation

Le problème & la solution

⚠ Le problème

Claude Code a une fenêtre de contexte limitée. Quand une session devient longue, les informations critiques se noient dans le bruit conversationnel : salutations, reformulations, brouillons, métadiscours. Claude perd le fil, répète des erreurs déjà résolues, oublie des décisions architecturales.

✓ La solution

compact-manager filtre sémantiquement la conversation pour ne garder que ce qui ne peut pas être reconstruit : décisions architecturales, constantes projet, bugs découverts, tâches en cours. Le snapshot est rechargé automatiquement à la session suivante.

🐍

Hook Python

compact-monitor.py surveille l'usage du contexte en temps réel et déclenche automatiquement à 65%.

🧠

Skill Claude

SKILL.md orchestre la compression sémantique : garde l'essentiel, drope le bruit, génère un snapshot structuré.

📚

Lessons System

Apprend tes préférences de filtrage via /compact-manager learn. DROP, KEEP, COMPRESS ou STYLE personnalisés.

Sémantique, pas mécaniqueContinuité réelle cross-sessionApprentissage progressifNon-intrusif — répond d'abord, compact en postfix

Architecture

Flux d'une session type

eventUserPromptSubmit

compact-monitor.py

Premier message

📋 Inject snapshot

Contexte ≥ 65%

⚡ Inject signal compact

compact-manager skill

Filtrage sémantiqueGénère snapshotSauvegarde fichiers

compact-latest.md

snapshot actuel

compact-prev.md

backup auto

compact-prefs.md

config + lessons

Continuité cross-session

Session A — longue

💬Messages 1, 2, 3...

⚠️Contexte atteint 65%

⚡Signal injecté dans le contexte

💬Claude répond normalement à l'user

📦Auto compact en postfix

✅compact-latest.md généré

Session B — nouvelle

💬Premier message utilisateur

🔍Hook détecte compact-latest.md

📋Inject snapshot → systemMessage

🧠Claude intègre le contexte A

✅Répond normalement

💬_(📋 contexte restauré)_ ajouté en fin

Installation

Prérequis & mise en place

Claude Code installé (claude --version)Python 3.10+ disponible (python3 --version)~/.claude/ configuré

RECOMMANDÉInstallation automatique

bash — via skills CLI

npx skills add ThomasRoger76/compact-manager

bash — manuel

git clone https://github.com/ThomasRoger76/compact-manager.git
cd compact-manager
bash install.sh

Le script vérifie les prérequis, copie les fichiers et met à jour settings.json automatiquement.

Installation manuelle

Créer les répertoires

mkdir -p ~/.claude/skills/compact-manager
mkdir -p ~/.claude/scripts

Copier les fichiers

# Skill (instructions pour Claude)
cp SKILL.md ~/.claude/skills/compact-manager/SKILL.md

# Hook Python (surveillance du contexte)
cp compact-monitor.py ~/.claude/scripts/compact-monitor.py
chmod +x ~/.claude/scripts/compact-monitor.py

# Lessons globales par défaut
cp compact-global-prefs.md ~/.claude/compact-global-prefs.md

Configurer le hook dans settings.json

~/.claude/settings.json

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 /home/ton-user/.claude/scripts/compact-monitor.py"
          }
        ]
      }
    ]
  }
}

Adapter le chemin à ton utilisateur.

Vérifier l'installation

/compact-manager status

Référence

Commandes

La seule invocation slash valide est /compact-manager. Le raccourci /cm est reconnu en texte libre dans la conversation mais pas comme slash command.

Slash command	Alias texte	Description
`/compact-manager`	`/cm`	Compact complet : filtrage, snapshot < 1500 tokens, backup, mise à jour compteurs, correction loop sur les items ambigus.
`/compact-manager quick`	`/cm quick`	Aperçu du snapshot sans rien écrire. Utile pour valider les lessons avant de committer un vrai compact.
`/compact-manager newsession`	`/cm newsession`	Ouvre un nouvel onglet Claude Code dans le même répertoire (WSL/Windows Terminal, macOS, tmux).
`/compact-manager auto`	`/cm auto`	Toggle AUTO_COMPACT enabled/disabled pour le projet courant. Affiche l'état actuel avant de basculer.
`/compact-manager learn`	`/cm learn`	Crée une lesson de filtrage (DROP/KEEP/COMPRESS/STYLE) scope G ou P, sauvegardée immédiatement.
`/compact-manager lessons`	`/cm lessons`	Affiche toutes les lessons actives : CORE globales, C globales, C projet.
`/compact-manager status`	`/cm status`	Config complète, taille du snapshot (chars + estimation tokens), aperçu 15 premières lignes, alerte qualité si AUTO_COMPACT_GEN ≥ 2.
`/compact-manager reset`	`/cm reset`	Supprime compact-latest.md, compact-prev.md, compact-prefs.md et .compact-session. Les lessons globales sont conservées.

Hook

Système de signaux

Le hook Python injecte des signaux dans le contexte de Claude via systemMessage. Ces signaux déclenchent automatiquement le comportement approprié.

📋[compact-manager]

Quand

Premier message d'une session si .claude/compact-latest.md existe.

Comportement

Claude intègre silencieusement le snapshot comme contexte de travail. À la fin de sa première réponse, il ajoute discrètement : _(📋 contexte précédent restauré — /compact-manager status pour voir)_. Ce message n'apparaît qu'une seule fois.

⚡[compact-monitor]

Quand

Contexte ≥ seuil configuré (défaut 65%), une seule fois par session (verrou .compact-session).

Comportement

Claude répond d'abord normalement à la question de l'utilisateur. Le compact s'exécute en postfix, après la réponse. Zero interruption garantie.

Filtrage

Règles hardcodées

DROPToujours supprimées

Règle	Exemple
Salutations, remerciements, validations	"ok", "parfait", "merci"
Questions déjà répondues plus tard	Question dont la réponse est visible plus bas
Brouillons remplacés par version finale	Premiers jets de code, tentatives ratées
Concepts documentés publiquement	Explication de ce qu'est un hook REST...
Reformulations du même point	Paraphrase sans information nouvelle
Métadiscours conversationnel	"je vais d'abord...", "on va structurer..."
Snapshots précédents dans la conversation	Compacts déjà effectués
Blocs de code identiques répétés	Garder uniquement le dernier

KEEPToujours conservées

Règle	Pourquoi
Anti-préférences explicites	✗ TensorFlow — non reconstructibles
Constantes projet	Ports, paths, timeouts — non reconstructibles
Décisions architecturales + raison	Éviter de re-décider chaque session
Tâches en cours (pas terminées)	Continuité du travail
Bugs et gotchas + solution	Éviter de retomber dans le même piège
Dernière version du code actif	Code encore utilisé
Contraintes non-évidentes	Limites API, comportements inattendus

Logique

Arbre de décision

Pour tout ce qui n'est ni clairement DROP ni clairement KEEP, l'arbre est appliqué dans l'ordre. Les lessons ont priorité sur les règles hardcodées.

Q1

Une lesson dit DROP pour ce type ?

OUI → DROPNON → passer à la question suivante

Q2

Une lesson dit KEEP pour ce type ?

OUI → KEEPNON → passer à la question suivante

Q2b

Une lesson dit COMPRESS (ET pas dans DROP hardcodé) ?

OUI → Inclure en 1 ligne max, facts essentiels uniquementNON → passer à la question suivante

Q3

Dans les règles DROP hardcodées ?

OUI → DROPNON → passer à la question suivante

Q4

Dans les règles KEEP hardcodées ?

OUI → KEEPNON → passer à la question suivante

Q5

Supersédée par une version plus récente dans la conversation ?

OUI → DROP — garder la version finaleNON → passer à la question suivante

Q6

Si ce contexte disparaît, l'info serait-elle perdue ? (non-reconstructible depuis fichier/code/doc)

OUI → KEEPNON → DROP (si non évident → ajouter à INCERTAINS_SUPPRIMÉS, max 5)

Défaut si encore incertain : KEEP — mieux vaut garder trop que perdre une info critique.

Personnalisation

Système de lessons

format d'une lesson

[L:{scope}:{cat}:{conf}] {règle} — {date (YYYY-MM-DD)}
  ⤷ {evidence / raison}

Champ	Valeurs	Description
`scope`	`G / P`	Global (tous projets) · Projet (ce projet uniquement)
`cat`	DROP	Toujours supprimer ce type de contenu
	KEEP	Toujours conserver ce type de contenu
	COMPRESS	Inclure en 1 ligne max, facts essentiels uniquement
	STYLE	Ajouter une section supplémentaire au snapshot
`conf`	CORE	Pré-seedé, immuable — ne pas supprimer
	C	Créé par l'utilisateur via /compact-manager learn

Lesson DROP — Supprimer systématiquement

[L:G:DROP:C] Logs de débogage et traces de stack — 2026-05-05
  ⤷ Jamais utiles dans le snapshot, toujours reconstructibles

Lesson KEEP — Toujours conserver

[L:P:KEEP:C] Schéma DB même partiel — 2026-05-05
  ⤷ Relations entre entités critiques pour comprendre le code

Lesson COMPRESS — Résumé 1 ligne

[L:P:COMPRESS:C] Historique des tentatives de déploiement — 2026-05-05
  ⤷ Utile mais 1 ligne suffit, pas besoin du détail complet

Lesson STYLE — Section supplémentaire dans le snapshot

[L:P:STYLE:C] Ajouter section "TESTS" avec résultats des derniers tests — 2026-05-05
  ⤷ Critique pour savoir où on en est sans relire la conversation

Règle fondamentale : Le compact applique les lessons — il ne les modifie jamais automatiquement. Seul /compact-manager learn crée ou modifie une lesson.

Snapshot

Formats de sortie

Mode Manuel — Riche (≤ 1500 tokens)

.claude/compact-latest.mdManuel

╔══════════════════════════════════════════════════╗
║ PROJECT MEMORY · mon-projet · Compact #3         ║
║ 2026-05-05                                       ║
╚══════════════════════════════════════════════════╝

▶ ÉTAT PROJET
Phase 2 du refactoring auth. Objectif : migrer de JWT
stateless vers sessions Redis. Blocage sur rotation clés.

▶ DÉCISIONS
• Redis pour sessions : latence < 5ms acceptable
• Pas de JWT : expérience équipe insuffisante

▶ FACTS UNIQUES
• Port Redis : 6380 | TTL session : 3600s
• Env staging : staging.monapp.internal

▶ STACK & ANTI-PRÉFÉRENCES
• Node.js 20 + Express ✗Fastify
• Passport.js + Redis ✗JWT ✗sessions mémoire

▶ EN COURS
• Migration middleware auth : 60%
  → implémenter rotation clés Redis

▶ BLOQUANTS / QUESTIONS OUVERTES
• Rotation clés Redis : valider approche blue/green

▶ PROFIL UTILISATEUR
• Préfère solutions simples
• Revue de code obligatoire avant merge

▶ CODE CRITIQUE
• auth/middleware.js:47 : workaround Passport v0.7.0
  (ne pas refactoriser)

Mode Auto — Ultra-compressé (≤ 800 tokens)

.claude/compact-latest.mdAuto ⚡

PROJECT mon-projet | Auto-compact #2 | 2026-05-05
PROJET  : Refactoring auth JWT → Redis sessions, phase 2

DÉCISIONS : Redis sessions (latence OK) | Pas JWT (expertise insuffisante)
FACTS     : Port 6380 | TTL 3600s | staging.monapp.internal
STACK     : Node.js+Express ✗Fastify | Passport.js+Redis ✗JWT
EN COURS  : Migration middleware 60% → rotation clés Redis
PREFS     : Solutions simples, revue avant merge

Aspect	Manuel	Auto
Taille cible	< 1500 tokens	< 800 tokens
Filtrage	Précis (arbre complet)	Agressif (DROP si ambigu)
Tracking incertains	Oui (correction loop)	Non
Lessons STYLE	Appliquées	Non appliquées
Backup auto	Oui	Oui

Configuration

Paramètres

Variable	Défaut	Description
`AUTO_COMPACT`	`enabled`	Active/désactive le compact automatique pour ce projet. Toggle avec /compact-manager auto.
`COMPACT_THRESHOLD`	`0.65`	Pourcentage du contexte conversationnel avant déclenchement. 0.50 pour déclencher plus tôt, 0.80 pour plus tard.
`CONTEXT_LIMIT`	`200000`	Fenêtre de contexte totale du modèle en tokens. Ajuster pour Haiku (100k) ou futurs modèles.
`COMPACT_STALE_DAYS`	`7`	Nombre de jours après lesquels un snapshot est considéré périmé et déclenche un avertissement.
`AUTO_COMPACT_GEN`	`0`	Compteur de générations auto consécutives sans compact manuel. Alerte qualité si ≥ 2.
`COMPACT_COUNT`	`0`	Nombre total de compacts effectués sur ce projet (manuel + auto). Informatif.

Mesure du contexte

context-measurement.pyHook Python

# Le hook mesure uniquement le contexte CONVERSATIONNEL
# Le system prompt (skills, plugins) est soustrait

system_baseline = first_turn.cache_creation_input_tokens
conversation    = last_turn.total_tokens - system_baseline
pct             = conversation / (CONTEXT_LIMIT - system_baseline)

# Déclenche ⚡ si pct >= COMPACT_THRESHOLD

Dépannage

Troubleshooting

Le signal ⚡ ne se déclenche pas

Hook configuré ?

cat ~/.claude/settings.json | grep -A5 "hooks"

Script Python fonctionnel ?

python3 ~/.claude/scripts/compact-monitor.py <<< '{}'

Doit afficher : {}

AUTO_COMPACT activé ?

/compact-manager status

Vérifier AUTO_COMPACT: enabled

Sentinel déjà présent (signal déjà envoyé cette session) ?

ls -la .claude/.compact-session

/compact-manager reset supprime le verrou

Le snapshot n'est pas rechargé en nouvelle session

Fichier existe ?

ls -la .claude/compact-latest.md

Fichier valide (> 1 ligne) ?

wc -l .claude/compact-latest.md

Est-ce bien le premier message ?

Le hook injecte le snapshot uniquement sur le premier message, avant toute réponse assistant.

Les lessons ne sont pas appliquées

Fichier global existe ?

ls ~/.claude/compact-global-prefs.md

Format correct ?

[L:G:DROP:C] ma règle — 2026-05-05
  ⤷ raison

Espaces, tirets longs — et indentation ⤷ obligatoires

AUTO_COMPACT_GEN >= 2 — Alerte qualité

Explication

2 compacts auto consécutifs sans compact manuel. La qualité du snapshot peut se dégrader par compression cumulative.

Solution

/compact-manager

Le compact manuel remet AUTO_COMPACT_GEN à 0

Fichiers

Structure des fichiers

Fichiers installés (globaux)

~/.claude/Global

~/.claude/
├── skills/
│   └── compact-manager/
│       └── SKILL.md              ← Instructions pour Claude
├── scripts/
│   └── compact-monitor.py        ← Hook Python (surveillance)
├── compact-global-prefs.md       ← Lessons globales CORE + C
└── settings.json                 ← Config Claude Code (hook ajouté)

Fichiers créés par projet

.claude/ (dans chaque projet)Projet

.claude/
├── compact-latest.md             ← Snapshot actuel (rechargé auto)
├── compact-prev.md               ← Backup du snapshot précédent
├── compact-prefs.md              ← Config + lessons projet (C)
└── .compact-session              ← Verrou anti-doublon par session

repo compact-manager/

compact-manager/
├── README.md
├── SKILL.md                      ← Copier vers ~/.claude/skills/
├── compact-monitor.py            ← Copier vers ~/.claude/scripts/
├── compact-global-prefs.md       ← Copier vers ~/.claude/
├── install.sh                    ← Script d'installation auto
└── examples/
    └── compact-prefs-example.md  ← Exemple de config projet

Prêt à installer compact-manager ?

MIT — libre d'utilisation, modification et distribution.

Voir sur GitHub ↗← Retour à Hubert