Codex Butler Bell

A polished desktop bell for the moment Codex is waiting.

Codex Butler Bell is a Codex plugin that shows a large animated bell overlay and plays a bell sound when Codex is waiting for a user action, such as a permission request, after a short delay.

Codex Butler Bell is useful when:

• You are running several Codex sessions and need to know which one needs attention.
• A waiting session is hidden behind other windows or on another macOS Space.
• Codex is blocked on a permission request and waiting for your approval.

It is intentionally small: a Codex hook, a detached watcher, and a native macOS Swift overlay helper.

Requirements

• macOS for the animated overlay and bundled sound playback.
• A Swift compiler from Xcode or the Xcode Command Line Tools. Without it, the plugin falls back to sound-only alerts.
• Codex with plugins and hooks enabled.

Install From A Local Clone

From this repo:

codex plugin marketplace add "$(pwd)"
codex plugin add codex-butler-bell@codex-butler-bell-local

Then start a new Codex thread so the plugin hooks are loaded.

Open /hooks in Codex to review and trust the bundled command hooks.

Install From GitHub

Install the published repository directly as a Git marketplace:

codex plugin marketplace add foxtrotdev/codex-butler-bell --ref main
codex plugin add codex-butler-bell@codex-butler-bell-local

Prompt To Paste Into Codex

Use this when you want Codex to install Codex Butler Bell for you:

Install the Codex Butler Bell Codex plugin from this GitHub repository:
foxtrotdev/codex-butler-bell

Run these commands:
1. codex plugin marketplace add foxtrotdev/codex-butler-bell --ref main
2. codex plugin add codex-butler-bell@codex-butler-bell-local

Then verify the install by listing plugins and tell me whether I need to start a
new Codex thread for hooks to load.

Try It

Run the overlay directly:

CODEX_BUTLER_BELL_VISIBLE_FOR_SECONDS=1.8 \
CODEX_BUTLER_BELL_RING_COUNT=4 \
CODEX_BUTLER_BELL_RING_SPEED=4.0 \
plugins/codex-butler-bell/scripts/codex-butler-bell-hook test-show

Run the test suite:

tests/test-codex-butler-bell.sh

How It Works

1. Codex fires PermissionRequest when it needs approval, or Stop after an assistant response.
2. The permission hook schedules an alert immediately. The stop hook schedules one only when last_assistant_message ends with ? or ？.
3. The watcher sleeps for CODEX_BUTLER_BELL_SHOW_AFTER_SECONDS.
4. If the user responds or the action proceeds, a prompt or tool hook runs codex-butler-bell-hook cancel.
5. If the marker is still present, the watcher builds and launches the Swift overlay.

The hook exits quickly. Delayed work happens outside the Codex hook process.

Configuration

Setting	Default	Meaning
CODEX_BUTLER_BELL_SHOW_AFTER_SECONDS	10	How long to wait before alerting.
CODEX_BUTLER_BELL_VISIBLE_FOR_SECONDS	1.8	How long the overlay stays visible.
CODEX_BUTLER_BELL_RING_SPEED	4.0	Bell swing speed, clamped to 0.25–4.0.
CODEX_BUTLER_BELL_RING_COUNT	4	Alternating swing count, clamped to 1–8.
CODEX_BUTLER_BELL_SOUND_START_DELAY_SECONDS	0.08	Sound delay after overlay start.
CODEX_BUTLER_BELL_SOUND_PATH	assets/bell.mp3	Bell sound file path (bundled). No fallback if invalid.
CODEX_BUTLER_BELL_CACHE_DIR	$TMPDIR/codex-butler-bell	Swift helper cache.
CODEX_BUTLER_BELL_STATE_DIR	plugin data	Hook state directory.

Privacy

The plugin runs locally. It does not send prompts, responses, or telemetry to an external service.

Sound Attribution

The bundled bell sound is Servant Bell Ring 1 by floraphonic. It is used under the Pixabay Content License and is not covered by the project's Apache License 2.0. See THIRD_PARTY_NOTICES.md for details.

Override it with CODEX_BUTLER_BELL_SOUND_PATH if you'd rather use your own.

License

Codex Butler Bell's original code and documentation are licensed under the Apache License 2.0. The bundled bell sound is licensed separately as described above.

Project Layout

.agents/plugins/marketplace.json
LICENSE
THIRD_PARTY_NOTICES.md
docs/assets/codex-permission-alert-demo.gif
plugins/codex-butler-bell/.codex-plugin/plugin.json
plugins/codex-butler-bell/LICENSE
plugins/codex-butler-bell/THIRD_PARTY_NOTICES.md
plugins/codex-butler-bell/hooks/hooks.json
plugins/codex-butler-bell/assets/bell.mp3
plugins/codex-butler-bell/scripts/codex-butler-bell-hook
plugins/codex-butler-bell/scripts/codex-butler-bell-watch
plugins/codex-butler-bell/scripts/CodexButlerBellOverlay.swift
plugins/codex-butler-bell/skills/codex-butler-bell/SKILL.md
tests/test-codex-butler-bell.sh