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