---
name: usage-install
description: >
  Install, verify, uninstall, or reconfigure the Claude plan usage hook — a
  PreToolUse hook that fires desktop notifications when the 5-hour session window
  or the weekly window of your Claude subscription runs high (from 90%, every 5%),
  shows the extra-usage surcharge past 100%, can block tool calls over a threshold,
  and on an API key estimates the session cost. All behaviour (thresholds,
  notification cadence, blocking / extra-usage policy, timeouts) lives in a config
  file re-read on every run. Use when the user says /usage-install, 'install the
  usage hook', 'surveille mon forfait Claude', 'alerte sur l usage', 'notifie quand
  je dépasse', 'hook usage session 5H', 'désinstalle le hook usage', 'uninstall
  usage hook', OR wants to change any setting: 'bloque au-delà de X%', 'bloque
  l extra usage', 'bloque au dépassement', 'pas d extra usage', 'autorise l extra
  usage', 'désactive le blocage', 'change le seuil d alerte', 'alerte plus tôt',
  'notifie moins/plus souvent', 'change la fréquence des notifications', 'notifs
  persistantes', 'montre la config usage', 'remets la config par défaut', 'block
  extra usage', 'allow overage', 'change the alert threshold', 'notify less often',
  or needs the Claude usage monitoring configured, reconfigured, or removed.
allowed-tools:
  - Bash
  - Read
  - Edit
  - Write
  - AskUserQuestion
---

Install, verify, uninstall, or **reconfigure** the Claude plan usage hook. It runs as a **PreToolUse** hook before every tool call. Behaviour:

- **Team/subscription plan** — reads usage from the OAuth endpoint (cached, ≤1 network call / 60s) and fires a **desktop notification** (+ a transcript message) for **one window at a time** — the one that crossed a threshold. Each window is configured **independently** (`[usage.five_hour]` / `[usage.seven_day]`) and can be **turned off** on its own. Defaults: the **5H window** notifies every **5%** from 90% **plus 98% and 99%** (then 100%, 105%…), the **weekly** window every **1%** from 90%. Each notification carries its own rhythm pictogram (🐢/✅/🔥) + pace + ETA. Past 100% it appends the **extra-usage surcharge accrued since the overage started**.
- **API key** — there is no plan window, so every token is billed: the hook treats it as permanent extra usage and notifies periodically with the **estimated session cost** (computed from the transcript × live per-token rates).
- **Blocking (per window)** — each **enabled** window's `block_at` > 0 **denies** tool calls once *that* window reaches its threshold (e.g. block on 5H at 100% while never blocking on the weekly). A window with `enabled = false` never blocks (master switch); `notification = false` mutes its notifications but keeps blocking. API-key mode counts as 100%, so any enabled window with `block_at ≤ 100` blocks per-token sessions. `block_at 100` = **no extra usage** (blocks exactly at the overage line). Off (`0`) by default on both windows.
- **Config-driven** — every setting lives in the `[usage]` table of pysae-ai-tools' central `config.toml` (OS config dir: `~/.config/pysae-ai-tools/config.toml` on Linux), **re-read on every tool call**: changes take effect **immediately**, with no edit to `settings.json` and no Claude Code restart. Manage it with `pysae-ai-tools usage config …` (see **Configuration** below) — never hand-edit the TOML.
- **Pricing** — per-token rates are **downloaded** from the official doc and cached (no hard-coded table); refreshed in the background and via `pysae-ai-tools usage pricing refresh`.
- **Native notifications** — uses the `desktop-notifier` library (D-Bus on Linux, UNUserNotifications on macOS, WinRT toast on Windows), with the bundled Claude logo as the icon. No shell-out. Notifications carry the gauges on one line (OS notification banners collapse newlines; the multi-line view with bars goes to the transcript message). Action buttons (Unblock/Block) work where the OS notification server supports them (dunst/mako/KDE/Windows) — **GNOME Shell does not render them**, so there the action stays reachable via `pysae-ai-tools usage unblock` / `block`.
- **CI-safe** — the hook is a no-op when `$CI` is set, so it never notifies or blocks a pipeline. It always exits 0 and is silent on any error.

## Routing — pick the intent first

- **Change / show / reset a setting** (thresholds, notification cadence, block or allow extra usage, timeouts) → go straight to **Step 5 — Configuration**. (No install/restart needed — config is live.)
- **Temporarily allow or force blocking for the current session/window** → **Step 6 — Temporary override**.
- **Uninstall** → **Step 4 — Uninstall**.
- Otherwise (install / first-time setup / verify) → **Step 1** onward.

## Step 1 — Check current state

```bash
pysae-ai-tools usage setup status
```

| Résultat | Action |
|---|---|
| `HOOK: CONFIGURED` | Aller au Step 3 (vérification) |
| `HOOK: NOT CONFIGURED` | Aller au Step 2 |
| Commande introuvable | Dire à l'utilisateur de lancer `cd <ai-tools repo> && bash install.sh` |

## Step 2 — Install

```bash
pysae-ai-tools usage setup install
```

Résultats possibles :
- `HOOK: INSTALLED` — succès
- `HOOK: ALREADY CONFIGURED` — déjà en place

La commande installée dans `settings.json` reste **un simple `pysae-ai-tools usage hook`, sans flags** : tout le réglage vit dans la config (Step 5), relue à chaque exécution.

## Step 3 — Verify

Vérifier que la lecture de l'usage fonctionne :

```bash
pysae-ai-tools usage show
```

Sur un forfait, doit afficher les deux jauges (Fenêtre 5H + Semaine) ; sur une clé API, affiche « Mode : clé API ». Si « Usage indisponible », le token Claude est absent/expiré (relancer une session Claude Code authentifiée) — sur macOS les credentials sont dans le Keychain, non lus par le hook. Ajouter `--notify` pour aussi envoyer une notification bureau de test.

Initialiser/vérifier le cache des tarifs (téléchargés) :

```bash
pysae-ai-tools usage pricing refresh
pysae-ai-tools usage pricing show
```

Tester le hook lui-même (seuil bas → doit émettre une notification + un JSON `systemMessage`), puis remettre le défaut :

```bash
pysae-ai-tools usage config set five_hour.alert_from 1
echo '{"session_id":"test","tool_name":"Bash"}' | pysae-ai-tools usage hook
pysae-ai-tools usage config set five_hour.alert_from 90
```

Dire à l'utilisateur :

> Le hook d'usage du forfait Claude est configuré. Avant chaque commande, il vérifie l'usage et **notifie sur le bureau dès 90 %, puis tous les 5 %** ; au-delà de 100 % il affiche le surcoût d'extra-usage. Sur une clé API, il estime le coût de la session. Le hook prend effet au **prochain démarrage** de Claude Code (ou via `/hooks`).
>
> Tous les réglages se changent à chaud avec `pysae-ai-tools usage config set <réglage> <valeur>` (relus à chaque tool call, sans redémarrage).

## Step 4 — Uninstall

```bash
pysae-ai-tools usage setup uninstall
```

Dire à l'utilisateur :

> Le hook d'usage a été désinstallé. Il ne sera plus appelé après redémarrage de Claude Code. La config (`usage config`) est conservée ; `pysae-ai-tools usage config reset` pour l'effacer.

## Step 5 — Configuration

Réglages persistants, **relus à chaque exécution du hook** → toute modification prend effet **immédiatement** (aucun redémarrage). Voir l'état courant : `pysae-ai-tools usage config show` (ou `--json`). Tout remettre par défaut : `pysae-ai-tools usage config reset`.

Modifier un réglage : `pysae-ai-tools usage config set <réglage> <valeur>`. Les réglages de seuil/cadence/blocage sont **par fenêtre**, sous les clés pointées `five_hour.*` (fenêtre 5H) et `seven_day.*` (semaine) ; les autres sont globaux.

**Par fenêtre** (`<win>` = `five_hour` ou `seven_day`) :

| Réglage | Défaut 5H / semaine | Effet | Augmenter / Diminuer |
|---|---|---|---|
| `<win>.enabled` | `true` / `true` | **interrupteur maître** de la fenêtre | `false` = coupe TOUT (ni notif **ni blocage**) |
| `<win>.notification` | `true` / `true` | active les **notifications** (le blocage reste indépendant) | `false` = pas de notif, mais `block_at` continue de bloquer |
| `<win>.block_at` | `0` / `0` | seuil % de **blocage** des tool calls pour cette fenêtre (`0` = jamais) | `100` = pas d'extra usage ; `<100` = marge |
| `<win>.alert_from` | `90` / `90` | % où démarrent les **alertes fines** | ↓ pour être prévenu plus tôt |
| `<win>.step` | `5` / `1` | **pas** des notifs au-dessus du seuil | ↑ = moins de notifs, ↓ = plus |
| `<win>.checkpoint_step` | `20` / `20` | paliers notifiés **quoi qu'il arrive** (20/40/60/80…) | `0` = désactive ces paliers |

Les notifications d'une fenêtre nécessitent `enabled` **et** `notification` à `true` ; le blocage nécessite `enabled` à `true` et `block_at > 0`. Donc `enabled false` désactive entièrement la fenêtre ; `notification false` ne coupe que les notifs en gardant le blocage.

**Globaux** :

| Réglage | Défaut | Effet | Augmenter / Diminuer |
|---|---|---|---|
| `notify_timeout` | `15000` | durée de vie des notifs en **ms** | `0` = persistant |
| `api_notify_interval` | `120` | anti-spam clé API (1 notif max / N **s**) | ↑ = moins de notifs |
| `pricing_ttl` | `604800` | TTL du cache des tarifs (**s**) | — |

**Cartographie intention → commande** (interpréter la demande en langage naturel ; viser la fenêtre nommée, sinon appliquer aux deux) :

- « bloque l'extra usage » / « bloque au dépassement » / « pas de dépassement » → `usage config set five_hour.block_at 100` **et** `usage config set seven_day.block_at 100`
- « bloque la 5H à 95 % » (marge avant l'extra) → `usage config set five_hour.block_at 95`
- « autorise l'extra usage » / « désactive le blocage » → `block_at 0` sur les deux fenêtres
- « désactive complètement la semaine » / « seulement la 5H » → `usage config set seven_day.enabled false` (coupe notif + blocage)
- « coupe juste les notifs de la semaine (garde le blocage) » → `usage config set seven_day.notification false`
- « réactive la semaine » → `usage config set seven_day.enabled true`
- « alerte-moi plus tôt / dès 80 % (5H) » → `usage config set five_hour.alert_from 80`
- « notifie moins souvent (5H) » → augmenter `five_hour.step` (ex. `10`) ; « plus souvent » → `2`
- « notifie moins souvent (semaine) » → augmenter `seven_day.step`
- « enlève les paliers intermédiaires (5H) » → `usage config set five_hour.checkpoint_step 0`
- « notifications persistantes » → `pysae-ai-tools usage config set notify_timeout 0`
- « moins de spam en clé API » → augmenter `api_notify_interval` (ex. `300`)
- « montre la config » → `pysae-ai-tools usage config show`
- « remets par défaut » → `pysae-ai-tools usage config reset`

**Activer le blocage** (`<win>.block_at`) : c'est une décision avec effet de bord (les tool calls seront refusés). Si la demande est explicite (« bloque au dépassement »), appliquer directement ; si elle est vague (« évite que je dépasse »), confirmer le seuil et la/les fenêtre(s) avec `AskUserQuestion` (ex. 100 % = aucune extra usage, 95 % = marge). En mode clé API, **tout** `block_at ≤ 100` (sur n'importe quelle fenêtre) bloque la session entière — le préciser à l'utilisateur.

Après modification, afficher la config résultante (`usage config show`) et préciser que **c'est déjà actif** (pas de redémarrage). Si le hook n'est pas encore installé (`setup status` → `NOT CONFIGURED`), proposer le Step 2 — sinon la config ne sera jamais lue.

## Step 6 — Temporary override (session / window)

Bascule ponctuelle (globale) qui **prime sur les `<win>.block_at`**, sans changer la config persistante. Le déblocage est calé sur la **window** courante (5H) et s'efface tout seul à son reset.

- « débloque l'extra usage pour cette session / jusqu'au reset » → `pysae-ai-tools usage unblock`
- « débloque pendant 30 min » → `pysae-ai-tools usage unblock --minutes 30`
- « rebloque maintenant » → `pysae-ai-tools usage block`

Pour un changement **durable** du comportement de blocage, utiliser `<win>.block_at` (Step 5), pas ces commandes.
