How it works
From hook to voice.
Every event takes the same short trip, and none of it leaves your Mac. Here it is end to end, along with the promises that hold at every step.
The pipeline
01
Hook fires
Your agent finishes, asks a question, or wants to run a gated command. Its hook calls the PingMyBell shim — a ~560 KB binary that starts in about 3 ms.
02
Loopback ingest
The shim posts the event to 127.0.0.1 with the per-install token. Anything without the token is rejected; anything malformed is dropped.
03
Registry
Each session moves through working → waiting on you → done in a local SQLite store. Summaries are stripped of markdown and paths and capped at 220 characters before anything is stored.
04
Voice and island
Approvals jump the speech queue ahead of completions, duplicates within 5 seconds are dropped, and the island updates at the same moment.
The promises
100% offline
Speech is your OS’s own engine. No cloud TTS, no LLM calls, no accounts. The only network traffic is loopback.
Fails open
The hook shims exit 0 silently on any error, or when the app isn’t running. A broken PingMyBell can never block or change what your agent does.
Your machine only
The ingest server binds 127.0.0.1 behind a per-install token. Config and history live in ~/.pingmybell/, readable by you alone.
Free and MIT
No subscription, no seat, no telemetry. Read every line of it on GitHub.
The integrations
| Agent | How it hooks in | Callouts | Approvals |
|---|---|---|---|
| Claude Code | Hooks merged into ~/.claude/settings.json — your existing hooks and settings are preserved, and uninstall removes exactly ours. | Yes | Opt-in: approve or deny gated tool calls (or hand them back to the terminal), and answer questions, from the island. |
| Codex CLI | Lifecycle hooks in Codex’s hooks.json, plus the notify slot as a fallback. | Yes | Opt-in: approve or deny command runs and file edits from the island, when Codex runs in a mode that asks for approval. |
Agents plug in through adapters, so new ones can be added without touching the core. PingMyBell also listens to the event stream of theSothis suite, so a failing gate in a watched repo rings within a couple of seconds. For the full technical design, read the architecture doc.