# PingMyBell

> Free, open-source voice notifications and a notch command center for AI coding agents. Claude Code and Codex speak the moment they finish or need you — 100% offline.

Run several agents in parallel and the bottleneck becomes you noticing them. PingMyBell gives each agent its own voice, speaks a one-line summary the moment a session finishes or blocks, and puts a command center in your notch — approve, deny, or jump to the terminal without hunting for it.

Status: Early alpha · macOS, from source. The full loop runs today on macOS 13+ and is gate-verified on real notch hardware. There are no signed prebuilt releases yet, so you build the app yourself. Windows is scaffolded against the platform APIs but has not been run there.

Runs on macOS 13+. MIT licensed. Source: https://github.com/Davidb3l/pingmybell

## Agents

### Claude Code

- Integration: Hooks merged into ~/.claude/settings.json — your existing hooks and settings are preserved, and uninstall removes exactly ours.
- Spoken callouts: yes
- Approvals: Opt-in: approve or deny gated tool calls (or hand them back to the terminal), and answer questions, from the island.
- Install: `/Applications/PingMyBell.app/Contents/MacOS/pingmybell install-claude`

### Codex CLI

- Integration: Lifecycle hooks in Codex’s hooks.json, plus the notify slot as a fallback.
- Spoken callouts: yes
- Approvals: Opt-in: approve or deny command runs and file edits from the island, when Codex runs in a mode that asks for approval.
- Install: `/Applications/PingMyBell.app/Contents/MacOS/pingmybell install-codex`, then `/Applications/PingMyBell.app/Contents/MacOS/pingmybell install-codex-hooks`

## Features

- A voice per agent: OS-native speech, a different default voice for each agent, with voice, rate and volume pickers per agent.
- Approvals from the notch: Turn it on from the bell, and Claude Code and Codex commands and file edits are approved or denied in one click. It never steals focus.
- Live ticker: While an agent works, the island shows what it is doing right now — the command, the file — without a sound.
- Triage hotkey: ⌃⌥Space jumps to the session that has waited longest. Press again to cycle through the rest.
- Jump to the session: Click any session to bring forward the app it runs in — any terminal, or the Claude desktop app — and its tmux pane if it has one. No permissions needed.
- Knows when to hush: If that session’s terminal is already in front of you, a chime replaces the sentence. Quiet hours mute it overnight.
- Morning digest: The first event of your day gets a one-sentence recap of what the fleet did since you left.
- The session board: Every live session, its state and how long it has been in it, with the last 50 events each.

## How an event becomes a sentence

1. 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.
2. 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.
3. 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.
4. 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.

## 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.

## Install from source

Requires: Bun, Rust (stable), macOS 13 or later.

```sh
git clone https://github.com/Davidb3l/pingmybell && cd pingmybell
bun install
bun run tauri build
```

## FAQ

### Does anything leave my machine?

No. Speech uses your OS’s built-in engine, and the app listens only on loopback. There are no accounts, no analytics and no update pings — the auto-updater is off by default.

### Will it break my agent if it crashes?

No. Every hook shim exits 0 silently on any internal error or when the app isn’t running, and an unanswered approval times out back to the agent’s own terminal prompt.

### Why build from source?

There are no signed prebuilt releases yet. Building takes Bun and stable Rust, and the README walks through it end to end.

### Windows? Linux?

The Windows platform layer is written against the Windows APIs but hasn’t been run or gated there. Linux isn’t built yet, though nothing in the design rules it out.

### Which agents does it support?

Claude Code and Codex CLI today. Agents plug in through adapters, so new ones can be added without touching the core.

## Pages

- [Home](https://pingmybell.com/)
- [How it works](https://pingmybell.com/how-it-works/)
- [Install](https://pingmybell.com/install/)