225 lines
8.3 KiB
Markdown
225 lines
8.3 KiB
Markdown
# 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](https://www.python.org/downloads/) ou installer via `winget install Python.Python.3`
|
|
- **macOS** : installer via `brew install python3` (requiert [Homebrew](https://brew.sh/))
|
|
- **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
|
|
|
|
```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` :
|
|
```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 :
|
|
|
|
```json
|
|
{
|
|
"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 :
|
|
```bash
|
|
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`
|