Bell

Desktop popup notifications that ring when Claude pauses on you.

• Claude Code: fires a popup on Stop (turn finished, only if the turn took >30s), Notification (Claude is idle or asking for permission), and SubagentStop.
• Claude Desktop: exposes an MCP tool notify_done(summary) that Claude calls when it finishes a task.

Clicking the popup dismisses it and can bring the relevant Claude, VS Code, or terminal window to the front.

Bell records local notification history in ~/.bell/history.sqlite3 using SQLite. Each row includes timestamp, source, title, message, and focus target.

Popups center on the monitor containing the current foreground window. If monitor detection fails, Bell falls back to the primary-display behavior.

Install

cd "C:\Users\<you>\Desktop\projects\bell"
py -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .

Test

python -m bell.notify "Bell" "Hello from Bell" none
echo '{"hook_event_name":"Stop","session_id":"test-session","cwd":"C:\\tmp","transcript_path":"","stop_hook_active":false}' | python -m bell.hook
python -m bell.codex_notify turn-ended
python -m bell.doctor

Claude Code Hooks

Do not wire this automatically from the repo build. In a later approved step, merge hook commands into the relevant Claude settings file.

Claude Desktop MCP

The MCP entry point is:

python -m bell.mcp_server

Codex Notify

Codex CLI/App can call Bell through its notify config:

notify = ["C:\\Users\\<you>\\Desktop\\projects\\bell\\.venv\\Scripts\\pythonw.exe", "-m", "bell.codex_notify"]

Bell only opens a popup for Codex completion notifications: either the turn-ended wrapper event or a JSON payload with type = "agent-turn-complete". Other Codex notify invocations are logged to ~/.bell/bell.log and skipped without writing history.