feat: context-warn extension — alert on context threshold

2026-05-23 20:16:39 +02:00
commit b6e38abf5e
4 changed files with 232 additions and 0 deletions
@@ -0,0 +1,79 @@
+# Context Warn Extension
+
+Emits a sound alert when the context window reaches or exceeds **100 000 tokens**. Also shows a UI notification and status bar update.
+
+## Installation
+
+### Option 1: Auto-discovered (recommended)
+
+```bash
+mkdir -p ~/.pi/agent/extensions/context-warn
+cp -r /home/enne2/base/context-warn-extension/* ~/.pi/agent/extensions/context-warn/
+```
+
+Then reload pi with `/reload`.
+
+### Option 2: One-off with --extension
+
+```bash
+pi -e /home/enne2/base/context-warn-extension/index.ts
+```
+
+## Features
+
+- **Sound alert**: Plays a pre-bundled WAV alert sound via `aplay` (no runtime generation)
+- **UI notification**: Shows a warning notification in the TUI
+- **Status bar**: Shows current token count and context window size
+- **Cooldown**: Only alerts once per threshold crossing, then waits 60 seconds before next alert
+- **Auto-reset**: Clears alert state after compaction
+
+## Commands
+
+- `/context-warn-status` — Show current context usage and alert status
+- `/context-warn-alert` — Manually trigger the alert sound (for testing)
+
+## Configuration
+
+Edit these values at the top of `index.ts`:
+
+| Constant | Default | Description |
+|----------|---------|-------------|
+| `WARNING_TOKEN_THRESHOLD` | 100 000 | Tokens at which to trigger the alert |
+| `CHECK_INTERVAL_MS` | 15 000 | How often to check context (ms) |
+| `WARNING_COOLDOWN_MS` | 60 000 | Minimum seconds between alerts |
+
+## Dependencies
+
+- `aplay` (ALSA player) — for playing the WAV file
+- `sox` — only needed to **generate** a new alert.wav (optional)
+
+Both are available on Fedora by default. On Ubuntu/Debian:
+```bash
+sudo apt install alsa-utils sox libsox-fmt-all
+```
+
+## How It Works
+
+1. Listens to `turn_end` events (fired after every LLM response)
+2. Calls `ctx.getContextUsage()` to check current token count
+3. When tokens ≥ threshold, plays `alert.wav` via aplay
+4. Shows a TUI notification and updates the status bar
+5. Resets alert state on `session_compact`
+
+## Alert Sound
+
+The bundled `alert.wav` is a **~0.85-second preallarme** — breve, chiaro, non fastidioso:
+- **2 beep corti** a 580 Hz (0.15s ciascuno) → "avviso"
+- **1 tono più lungo** a 880 Hz (0.55s) → "attenzione"
+- Totale: ~1 secondo — sufficiente per accorgersene senza essere invasivo
+
+### Regenerate con SoX
+
+```bash
+sox -n -t wav a.wav synth 0.15 sine 580 vol 0.55
+sox -n -t wav b.wav synth 0.15 sine 580 vol 0.55
+sox -n -t wav c.wav synth 0.55 sine 880 vol 0.65
+sox a.wav b.wav c.wav alert.wav
+```
+
+Customize the tone by changing the frequency and volume parameters.