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)

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

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)
• /speak <text> — Speak the text aloud via TTS (for the agent to vocalize conclusions)

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:

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

Customize the tone by changing the frequency and volume parameters.