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)

pi install git:git.enne2.net/enne2/context-warn@main

Or pin to a specific tag:

pi install git:git.enne2.net/enne2/context-warn@v1.0.0

Via --extension (test without installing)

pi -e git:git.enne2.net/enne2/context-warn

Manual install

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:

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

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:

pi update git:git.enne2.net/enne2/context-warn

To remove:

pi remove git:git.enne2.net/enne2/context-warn