AI-translated from English; not yet reviewed by a fluent editor.

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

> Installez un petit hook SessionStart du projet pour ajouter la branche Git actuelle au contexte de Claude Code. Vérifiez sa sortie directe, le démarrage, la reprise et les échecs.

By BIG CHANGE Editorial

Published: 2026-10-20T00:22:54.831Z
Updated: 2026-10-20T00:22:54.831Z
Canonical: https://bigchange.ai/blog/claude-code-session-start-branch-context-hook-guide

![Conceptual charcoal illustration of an unbranded desktop monitor with one short orange stroke above two soft charcoal strokes; a keyboard rests in front.](https://bigchange.ai/api/media/file/claude-code-session-start-context-hero-v2.png)
AI-generated conceptual illustration by BIG CHANGE; no actual Claude Code interface, hook execution or model result is depicted.

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](https://code.claude.com/docs/en/hooks), 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](https://code.claude.com/docs/en/data-usage) 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` :

```javascript
'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.

```json
{
  "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 :

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

Dans Bash :

```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](https://code.claude.com/docs/en/costs) 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](https://bigchange.ai/blog/claude-code-session-context-continue-guide) 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](https://code.claude.com/docs/en/hooks) — 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](https://code.claude.com/docs/en/hooks-guide) — 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](https://code.claude.com/docs/en/setup) — 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](https://code.claude.com/docs/en/data-usage) — 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](https://code.claude.com/docs/en/costs) — 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.

## Sources

- [Référence des hooks Claude Code](https://code.claude.com/docs/en/hooks) — Manuel principal actuel d’Anthropic vérifié contre l’instantané approuvé du 19 octobre 2026, puis pendant la rédaction. Il établit les sources startup/resume de SessionStart et les filtres, command et args en forme exec, la variable racine du projet, stdout comme contexte, l’observation des paramètres, la confiance, les journaux, l’exécutable réel sous Windows et les erreurs SessionStart non bloquantes. Il décrit le produit ; BIG CHANGE n’a exécuté aucun hook lancé par Claude. Aucune date fixe de révision du manuel n’était indiquée.
- [Automatiser les actions avec les hooks](https://code.claude.com/docs/en/hooks-guide) — Guide officiel d’Anthropic pour l’installation et les tests. Il appuie la configuration et les diagnostics du lecteur, sans prétendre que BIG CHANGE a exécuté l’exemple dans Claude Code. Le script Node limité et les paramètres viennent du dossier d’implémentation local examiné séparément.
- [Configuration avancée de Claude Code](https://code.claude.com/docs/en/setup) — Référence officielle d’installation et d’environnement pour vérifier la configuration locale. La préparation a seulement observé la version 2.1.301 ; cette source n’en fait pas une version minimale.
- [Utilisation des données de Claude Code](https://code.claude.com/docs/en/data-usage) — Conditions officielles dépendant du compte. Le guide demande de les examiner avant d’envoyer une branche au modèle ; filtrage et troncature n’empêchent pas son nom de révéler un client ou un incident confidentiel. Aucune garantie générale de confidentialité n’en est déduite.
- [Gérer les coûts efficacement](https://code.claude.com/docs/en/costs) — Conseils officiels sur compte et utilisation du modèle pour les tests interactifs de démarrage et reprise. Le script local n’appelle ni réseau ni modèle, tandis que les sessions peuvent consommer un quota de forfait, de fournisseur ou d’API. Aucun prix fixe ni test payant n’est affirmé.
- [Comment inspecter le contexte et poursuivre une session Claude Code](https://bigchange.ai/blog/claude-code-session-context-continue-guide) — Article antérieur BIG CHANGE 414, cité seulement pour le lien contextuel et la classification du rapport entre articles. Il traite d’une conversation existante et de sa poursuite ; ce n’est ni une preuve d’implémentation du hook ni un parent d’événement daté.