traduction
This commit is contained in:
@@ -0,0 +1,224 @@
|
||||
# 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`
|
||||
Reference in New Issue
Block a user