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