105 lines
2.8 KiB
Markdown
105 lines
2.8 KiB
Markdown
# 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
|
|
|
|
### Via `pi install` (recommended)
|
|
|
|
```bash
|
|
pi install git:git.enne2.net/enne2/context-warn@main
|
|
```
|
|
|
|
Or pin to a specific tag:
|
|
|
|
```bash
|
|
pi install git:git.enne2.net/enne2/context-warn@v1.0.0
|
|
```
|
|
|
|
### Via `--extension` (test without installing)
|
|
|
|
```bash
|
|
pi -e git:git.enne2.net/enne2/context-warn
|
|
```
|
|
|
|
### Manual install
|
|
|
|
```bash
|
|
mkdir -p ~/.pi/agent/extensions/context-warn
|
|
cp -r ~/.pi/agent/git/git.enne2.net/enne2/context-warn/* ~/.pi/agent/extensions/context-warn/
|
|
```
|
|
|
|
Then reload pi with `/reload`.
|
|
|
|
## 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` in the installed package:
|
|
|
|
| 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
|
|
```
|
|
|
|
## Package
|
|
|
|
This is a pi package. To update to the latest version:
|
|
|
|
```bash
|
|
pi update git:git.enne2.net/enne2/context-warn
|
|
```
|
|
|
|
To remove:
|
|
|
|
```bash
|
|
pi remove git:git.enne2.net/enne2/context-warn
|
|
```
|