pi-meditate

Close your eyes while Pi works. Hear a chime when it needs you.

A small extension for Pi's interactive terminal, using the lifecycle APIs in @earendil-works/pi-coding-agent 0.85.1 or newer. No runtime dependencies, model calls, telemetry, or transcript changes.

Install

pi install npm:pi-meditate

Run /reload in an existing Pi session, then:

/meditate

The command toggles meditation mode. It starts off on first use and remembers your choice for future sessions. Other already-open sessions keep their own setting.

While Pi works, a small reminder appears above the editor, alongside the normal streaming output:

Close your eyes. Take a slow, comfortable breath. Relax until the chime.

There is no speech, breathing metronome, or background music. A single bundled 3.5-second meditation-bowl-style chime plays as soon as:

• The whole task finishes, including tool calls, retries, compaction recovery, and queued continuations.
• The task stops because of an error or cancellation.
• A blocking extension UI prompt asks for your input, including permission prompts using Pi's UI APIs.

After you answer a prompt, the reminder returns if work continues. Pi chimes again when that work finishes. Very short tasks chime too. Idle menus do not chime. Turning meditation off clears the reminder and suppresses subsequent chimes; exiting or reloading Pi does not chime.

Audio plays through the system's current output device even when another application has focus. System mute and volume still apply. macOS uses afplay, Linux uses paplay, and Windows uses PowerShell's System.Media.SoundPlayer. Playback failures are silent and never interrupt Pi; there is no setup detection or fallback workflow.

Saved preference

The enabled/disabled default is stored as a JSON boolean in:

~/.agentic/config/pi-meditate.json

Setting AGENTIC_HOME changes the .agentic root. Writes replace the preference atomically. If multiple sessions toggle it, the last successful save becomes the default for future sessions. Each running session remains independent. A resumed or reloaded session reads the latest saved default.

Scope

Local interactive terminals on macOS, Linux, and Windows. No print/JSON/RPC notifications, SSH audio forwarding, separate background-subagent notifications, custom sound settings, or meditation tracking. This extension responds to Pi's documented lifecycle events, not arbitrary text printed by other extensions.

Development and verification

npm ci
npm run typecheck
npm test
pi -e ./index.ts

Tests cover lifecycle transitions, persistence, concurrent-session independence, audio command construction, failure isolation, and loading through Pi's real extension loader. Audio playback is mocked in automated tests.

Manual check:

1. Run /meditate, then ask Pi to run a short command and summarize its result. Confirm the reminder stays visible through tools and disappears with one chime at the end.
2. Trigger a permission prompt. Confirm one chime, no reminder while waiting, and the reminder's return when work resumes.
3. Cancel a running task with Escape. Confirm a chime. Run a short task while another app has focus and confirm its completion is audible.
4. Restart Pi and verify the setting survived. Keep a second session open and verify toggling one does not change the other.
5. Toggle off and repeat a task. Confirm there is no reminder or chime.

Validation during development: all 15 automated tests and type-checking passed on macOS, and afplay assets/chime.wav exited successfully. Windows and Linux playback still require real-device verification. A successful audio process exit is not a listening review; the interactive checklist above also remains a manual check.

The bundled WAV is a synthesized meditation-bowl approximation, not a recording: mono 16-bit PCM, 22,050 Hz, a soft strike with a 300 Hz base, inharmonic overtones, gently beating frequency pairs, and a 3.5-second fade. Regenerate it with node scripts/generate-chime.mjs from the source checkout. It is covered by the package's MIT license.