claude-code-best-practice/fr/.codex/hooks/HOOKS-README.md

HOOKS-README

Contient tous les détails, scripts et instructions pour les hooks Codex CLI.

Vue d'ensemble des événements hook

Codex CLI fournit 8 hooks via hooks.json :

#	Hook	Type d'événement	Fichier de config	Description
1	SessionStart	SessionStart	hooks.json	S'exécute une fois au démarrage de session — injecte du contexte + joue un son
2	PreToolUse	PreToolUse	hooks.json	S'exécute avant l'exécution d'un outil — joue un son
3	PermissionRequest	PermissionRequest	hooks.json	S'exécute quand Codex demande une approbation pour une opération sensible — joue un son
4	PostToolUse	PostToolUse	hooks.json	S'exécute après la fin d'un outil — joue un son
5	Stop	stop	hooks.json	S'exécute quand la session se termine — joue un son
6	UserPromptSubmit	UserPromptSubmit	hooks.json	S'exécute quand l'utilisateur soumet un prompt — joue un son
7	PreCompact	PreCompact	hooks.json	S'exécute avant la compaction du contexte — joue un son
8	PostCompact	PostCompact	hooks.json	S'exécute après la compaction du contexte — joue un son

Comment les hooks sont appelés

Tous les hooks (hooks.json) sont appelés avec le flag --hook :

python3 .codex/hooks/scripts/hooks.py --hook SessionStart
python3 .codex/hooks/scripts/hooks.py --hook PreToolUse
python3 .codex/hooks/scripts/hooks.py --hook PermissionRequest
python3 .codex/hooks/scripts/hooks.py --hook PostToolUse
python3 .codex/hooks/scripts/hooks.py --hook Stop
python3 .codex/hooks/scripts/hooks.py --hook UserPromptSubmit
python3 .codex/hooks/scripts/hooks.py --hook PreCompact
python3 .codex/hooks/scripts/hooks.py --hook PostCompact

Injection de contexte SessionStart

Le hook SessionStart écrit du contexte sur stdout, qui alimente directement la fenêtre de contexte du modèle. Cela inclut :

• Date/heure courante
• Nom de branche Git
• Statut du working tree (propre ou changements non commités)
• Chemin du répertoire de travail

Prérequis

Avant d'utiliser les hooks, assure-toi d'avoir Python 3 installé sur ton système.

Logiciels requis

Toutes plateformes (Windows, macOS, Linux)

• Python 3 : requis pour lancer le script hook
• Vérifier l'installation : python3 --version

Instructions d'installation :

• Windows : télécharger depuis python.org ou installer via winget install Python.Python.3
• macOS : installer via brew install python3 (requiert Homebrew)
• Linux : installer via sudo apt install python3 (Ubuntu/Debian) ou sudo yum install python3 (RHEL/CentOS)

Lecteurs audio (détectés automatiquement)

Le script hook détecte et utilise automatiquement le lecteur audio approprié pour ta plateforme :

• macOS : utilise afplay (intégré, aucune installation nécessaire)
• Linux : utilise paplay depuis pulseaudio-utils — installer via sudo apt install pulseaudio-utils
• Windows : utilise le module intégré winsound (inclus avec Python)

Fichiers de configuration

Il y a deux fichiers de configuration :

1. .codex/hooks.json — enregistre les hooks SessionStart, PreToolUse, PermissionRequest, PostToolUse, Stop, UserPromptSubmit, PreCompact et PostCompact
2. .codex/hooks/config/hooks-config.json — active/désactive les hooks individuels et le logging

hooks.json

{
  "hooks": {
    "SessionStart": [
      {
        "type": "shell",
        "command": "python3 .codex/hooks/scripts/hooks.py --hook SessionStart",
        "statusMessage": "Initializing session hooks...",
        "timeout": 10
      }
    ],
    "PreToolUse": [
      {
        "type": "shell",
        "command": "python3 .codex/hooks/scripts/hooks.py --hook PreToolUse",
        "statusMessage": "Running pre-tool-use hook...",
        "timeout": 10
      }
    ],
    "PermissionRequest": [
      {
        "type": "shell",
        "command": "python3 .codex/hooks/scripts/hooks.py --hook PermissionRequest",
        "statusMessage": "Running permission request hook...",
        "timeout": 10
      }
    ],
    "PostToolUse": [
      {
        "type": "shell",
        "command": "python3 .codex/hooks/scripts/hooks.py --hook PostToolUse",
        "statusMessage": "Running post-tool-use hook...",
        "timeout": 10
      }
    ],
    "Stop": [
      {
        "type": "shell",
        "command": "python3 .codex/hooks/scripts/hooks.py --hook Stop",
        "statusMessage": "Running session stop hook...",
        "timeout": 10
      }
    ],
    "UserPromptSubmit": [
      {
        "type": "shell",
        "command": "python3 .codex/hooks/scripts/hooks.py --hook UserPromptSubmit",
        "statusMessage": "Running user prompt submit hook...",
        "timeout": 10
      }
    ],
    "PreCompact": [
      {
        "type": "shell",
        "command": "python3 .codex/hooks/scripts/hooks.py --hook PreCompact",
        "statusMessage": "Running pre-compact hook...",
        "timeout": 10
      }
    ],
    "PostCompact": [
      {
        "type": "shell",
        "command": "python3 .codex/hooks/scripts/hooks.py --hook PostCompact",
        "statusMessage": "Running post-compact hook...",
        "timeout": 10
      }
    ]
  }
}

Configurer les hooks (activer/désactiver)

Désactiver des hooks individuels

Édite .codex/hooks/config/hooks-config.json :

{
  "disableSessionStartHook": false,
  "disablePreToolUseHook": false,
  "disablePermissionRequestHook": false,
  "disablePostToolUseHook": false,
  "disableStopHook": false,
  "disableUserPromptSubmitHook": false,
  "disablePreCompactHook": false,
  "disablePostCompactHook": false,
  "disableLogging": true
}

Options de configuration :

• disableSessionStartHook : mettre true pour désactiver l'injection de contexte et le son au démarrage de session
• disablePreToolUseHook : mettre true pour désactiver le son pre-tool-use
• disablePermissionRequestHook : mettre true pour désactiver le son de demande de permission
• disablePostToolUseHook : mettre true pour désactiver le son post-tool-use
• disableStopHook : mettre true pour désactiver le son d'arrêt de session
• disableUserPromptSubmitHook : mettre true pour désactiver le son de soumission de prompt utilisateur
• disablePreCompactHook : mettre true pour désactiver le son pre-compact
• disablePostCompactHook : mettre true pour désactiver le son post-compact
• disableLogging : mettre true pour désactiver le logging des événements hook vers .codex/hooks/logs/hooks-log.jsonl

Fallback de configuration

Il y a deux fichiers de configuration :

1. .codex/hooks/config/hooks-config.json - configuration partagée/par défaut commitée dans git
2. .codex/hooks/config/hooks-config.local.json - tes overrides personnels (ignorés par git)

Le fichier de config local (.local.json) prend le dessus sur la config partagée, ce qui permet à chaque développeur de personnaliser le comportement des hooks sans affecter l'équipe.

Configuration locale (overrides personnels)

Crée ou édite .codex/hooks/config/hooks-config.local.json pour tes préférences personnelles :

{
  "disableSessionStartHook": false,
  "disablePreToolUseHook": false,
  "disablePermissionRequestHook": false,
  "disablePostToolUseHook": false,
  "disableStopHook": true,
  "disableUserPromptSubmitHook": false,
  "disablePreCompactHook": false,
  "disablePostCompactHook": false,
  "disableLogging": true
}

Logging

Quand le logging est activé ("disableLogging": false), les événements hook sont écrits dans .codex/hooks/logs/hooks-log.jsonl au format JSON Lines. Chaque entrée contient le payload JSON complet reçu depuis Codex CLI.

Tests

Lancer la suite de tests :

python3 -m unittest tests.test_hooks -v

Voix

site utilisé pour générer les sons : https://elevenlabs.io/ voix utilisée : Adam - American, Dark and Tough

Extensibilité future

Ce projet peut être étendu en :

1. Ajoutant de nouvelles entrées à HOOK_SOUND_MAP dans hooks.py
2. Ajoutant les fichiers son correspondants dans .codex/hooks/sounds/
3. Ajoutant des clés de toggle dans hooks-config.json
4. Ajoutant de nouvelles entrées hook dans hooks.json