Ajouter un hook de contexte limité au projet au démarrage de Claude Code

Un hook Claude Code est une commande que l’application lance à un moment nommé de la session. Ce guide ajoute un hook SessionStart propre au projet qui lit la branche Git actuelle et fournit une courte ligne de contexte au démarrage ou à la reprise d’une conversation. Il suit la référence actuelle des hooks d’Anthropic, vérifiée le 19 octobre 2026. BIG CHANGE a testé le script directement avec Node et vérifié le JSON des paramètres ; nous n’avons ni exécuté un hook dans Claude Code ni testé de réponse du modèle.

Le grand changement

• Ce qui change : Ce hook de projet SessionStart fournit une courte ligne indiquant la branche Git au démarrage ou à la reprise d’une conversation dans Claude Code.
• Pourquoi cela compte : La branche actuelle arrive dans le contexte au démarrage ou à la reprise, sans collage manuel à chaque fois.
• À surveiller : Le contexte n’impose aucune règle et ne garantit aucune réponse. Vérifiez sa transmission réelle au démarrage et à la reprise dans votre projet de confiance.

Avant l’installation

Utilisez un projet Git que vous êtes autorisé à modifier. Il faut Claude Code, Node.js et Git dans le même terminal, ainsi que l’autorisation de modifier le fichier .claude/settings.json du projet. Vérifiez node --version, git --version et claude --version. L’hôte de préparation avait Claude Code 2.1.301 et Node 24.19.0 ; ces versions observées ne sont pas des exigences minimales.

Examinez le nom de branche avant de le transmettre à un modèle. Il peut révéler un client, un ticket ou un incident. Filtrer les caractères et raccourcir la chaîne n’en supprime pas le sens. N’installez cet exemple que si le nom est autorisé dans le contexte du modèle. Sinon, adaptez le script pour émettre un état approuvé et non sensible, puis faites examiner cette modification avant installation. La documentation d’Anthropic sur les données explique leur traitement par le service ; appliquez aussi vos autorisations de projet.

Les commandes des hooks s’exécutent avec vos droits utilisateur. Avant activation, inspectez les hooks existants du projet et de l’utilisateur, la politique de l’organisation et le script entier. Les paramètres du projet peuvent être versionnés ; .claude/settings.local.json reste local. L’exemple utilise les paramètres du projet pour y limiter la configuration.

Installer les deux fichiers

1. Créez .claude/hooks/ dans le projet. Enregistrez tout ce bloc sous .claude/hooks/session-context.cjs :

'use strict';

const { execFileSync } = require('node:child_process');

const project = process.env.CLAUDE_PROJECT_DIR;
if (!project) {
  process.stderr.write('CLAUDE_PROJECT_DIR is unavailable\n');
  process.exit(1);
}

try {
  const raw = execFileSync('git', ['-C', project, 'branch', '--show-current'], {
    encoding: 'utf8',
    timeout: 1500,
    maxBuffer: 4096,
    stdio: ['ignore', 'pipe', 'pipe'],
  }).trim();
  const branch = raw ? raw.replace(/[^A-Za-z0-9._/-]/g, '_').slice(0, 80) : 'detached HEAD';
  process.stdout.write(`Current project branch: ${branch}\n`);
} catch {
  process.stderr.write('Could not read the project branch; check Git and project path\n');
  process.exit(1);
}

Le processus Git enfant est limité à 1,5 seconde et à un tampon de sortie de 4 096 octets. Un résultat de branche vide, notamment en état HEAD détaché, devient detached HEAD. Un chemin de projet absent ou un échec Git produit un court diagnostic sur stderr et un code de sortie 1.

2. Ouvrez votre fichier .claude/settings.json existant. Fusionnez l’entrée hooks.SessionStart ci-dessous avec les autres paramètres et groupes de hooks, sans effacer les entrées existantes. Le bloc montre le contenu complet de settings.example.json dans le dossier examiné. Si le fichier contient déjà des entrées SessionStart , ajoutez ce groupe à leur tableau au lieu de le remplacer.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "node",
            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/session-context.cjs"],
            "timeout": 5
          }
        ]
      }
    ]
  }
}

Le filtre couvre une nouvelle session et une session reprise. Anthropic documente aussi clear, compact et fork comme sources de SessionStart ; cet exemple les exclut volontairement. Le champ args sélectionne la forme exec : Claude Code lance node avec le chemin résolu du script comme argument unique, sans interprétation ni guillemets de shell. Sous Windows, node.exe doit correspondre à un véritable exécutable ; un relais .cmd ne convient pas à cette forme. Le délai de cinq secondes du hook est distinct de celui de 1,5 seconde du processus Git.

Vérifier le script, puis Claude Code

3. Avant d’ouvrir Claude Code, lancez le script dans le terminal du projet et comparez sa sortie à Git. Dans PowerShell :

$env:CLAUDE_PROJECT_DIR = (Get-Location).Path
node .claude/hooks/session-context.cjs
git branch --show-current

Dans Bash :

CLAUDE_PROJECT_DIR="$PWD" node .claude/hooks/session-context.cjs
git branch --show-current

Attendez exactement une ligne sur stdout, Current project branch: BRANCH, où BRANCH est le résultat Git après filtrage des caractères et limitation à 80 caractères. En état HEAD détaché, le script affiche Current project branch: detached HEAD. Le test direct prouve seulement que le script local fonctionne dans ce terminal. Lors de notre préparation, sa branche ordinaire correspondait à Git ; les chemins de projet absents ou invalides donnaient stdout vide, un diagnostic sur stderr et une sortie 1. Nous avons inspecté dans le code la limite des noms longs et le repli en HEAD détaché, sans exécuter ces cas.

4. Démarrez un nouveau processus Claude Code interactif dans le projet de confiance avec claude --debug-file STARTUP_PRIVATE_LOG, en choisissant un chemin privé sous votre contrôle. Examinez les hooks du projet et de l’utilisateur avant d’accepter la confiance dans l’espace de travail. Cherchez dans le journal de débogage un événement SessionStart de source startup, le chemin du script sélectionné, son état de sortie et le traitement de sa sortie. Demandez à Claude quelle branche il a reçue en contexte, sans lui permettre d’utiliser un outil ni de relire Git. Comparez sa réponse et le journal au résultat direct. La sortie stdout du hook entre dans le contexte ; son affichage comme message dans l’interface n’est pas garanti.
5. Quittez cette session. Reprenez-la dans un autre processus avec claude --debug-file RESUME_PRIVATE_LOG --resume, puis vérifiez l’événement SessionStart resume et répétez la question sans outil ni nouvelle lecture de Git. Gardez les deux journaux privés : ils peuvent révéler des détails du projet. Une exécution non interactive -p ou via SDK n’affiche pas la même demande de confiance et peut lancer automatiquement les hooks du dépôt ; utilisez donc le parcours interactif pour cette vérification. Anthropic indique que son observateur de fichiers reprend normalement les changements de paramètres, mais un nouveau processus donne un test plus clair du démarrage et de la reprise.

Si le travail normal modifie ensuite la branche, répétez le test direct et démarrez une nouvelle session pour vérifier la ligne. Ne changez pas de branche uniquement pour prétendre que ce guide a été testé.

Si le hook ne s’exécute pas

Partez du résultat direct, puis vérifiez la fusion JSON, l’orthographe de SessionStart , le filtre startup|resume , le chemin racine du projet, la disponibilité de node et git, la confiance dans l’espace de travail et les erreurs de débogage. L’absence de CLAUDE_PROJECT_DIR écrit CLAUDE_PROJECT_DIR is unavailable sur stderr. Un chemin incorrect ou un échec Git écrit Could not read the project branch; check Git and project path. Dans les deux cas, le script sort avec 1 sans ligne de contexte. Un échec de SessionStart est un diagnostic non bloquant ; il ne peut pas servir de barrière d’action. Anthropic documente PreToolUse pour contrôler une action d’outil ; c’est un autre événement qui nécessite sa propre conception examinée.

Le script exécute seulement Git localement, sans requête réseau ni appel de modèle. Les vérifications de démarrage, reprise et réponse peuvent consommer votre quota de compte, de fournisseur ou de modèle ; le guide des coûts d’Anthropic donne les conditions actuelles. Ce guide ne fixe aucun prix et ne rapporte aucun test de session payante.

Pour une tâche distincte après le début d’une conversation, notre guide d’inspection du contexte et de poursuite d’une session Claude Code couvre l’examen du contexte et la continuation. Il ne configure pas ce hook de démarrage.

Sources et lectures complémentaires

• Anthropic, Référence des hooks Claude Code — Spécification principale actuelle vérifiée le 19 octobre 2026. Elle documente les sources et filtres de SessionStart , la forme exec args, les variables de chemin, stdout comme contexte, le rechargement des paramètres, la confiance, les journaux et les échecs non bloquants. C’est une documentation, pas une exécution de hook par BIG CHANGE.
• Anthropic, Automatiser les actions avec les hooks — Guide officiel d’installation et de test. Le script et les paramètres précis ci-dessus sont un exemple limité de BIG CHANGE examiné pour ce guide, pas un résultat de test copié du fournisseur.
• Anthropic, Configuration de Claude Code — Installation et prérequis d’environnement. Consultez les instructions actuelles de votre plateforme avant d’utiliser l’exemple.
• Anthropic, Utilisation des données de Claude Code — Conditions actuelles du fournisseur à examiner avant de mettre les informations de branche dans le contexte du modèle ; l’autorisation de votre projet reste une décision distincte.
• Anthropic, Gérer les coûts efficacement — Conseils actuels sur le compte et l’usage pour les tests interactifs. Le script Git local lui-même n’appelle ni modèle ni réseau.