# 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`