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

Listens to turn_end events (fired after every LLM response)
Calls ctx.getContextUsage() to check current token count
When tokens ≥ threshold, plays alert.wav via aplay
Shows a TUI notification and updates the status bar
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.

2.6 KiB Raw Permalink Blame History