# 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

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

## Test

```powershell
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:

```powershell
python -m bell.mcp_server
```

## Codex Notify

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

```toml
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.