foxtrotdev/codex-butler-bell

Analysis updated 2026-05-18

★ 1ShellAudience · developerComplexity · 2/5LicenseSetup · moderate

Mindmap

mindmap
  root((Codex Butler Bell))
    What it does
      Bell overlay on screen
      Bell sound alert
      Cancel on response
    When it fires
      Permission request
      Question-ending stop
    Configuration
      Delay before alert
      Overlay duration
      Custom sound path
    Tech
      Swift overlay
      Shell hooks
      Runs locally

mindmap root((Codex Butler Bell)) What it does Bell overlay on screen Bell sound alert Cancel on response When it fires Permission request Question-ending stop Configuration Delay before alert Overlay duration Custom sound path Tech Swift overlay Shell hooks Runs locally

Click or tap to explore — scroll the page freely

What do people build with it?

USE CASE 1

Get a visual and audio alert when a Codex session blocked on a permission request needs your approval, without watching the terminal.

USE CASE 2

Monitor multiple Codex sessions running in parallel and know which one needs attention.

USE CASE 3

Adjust the bell delay and overlay duration to match your working style using environment variables.

USE CASE 4

Replace the bundled bell sound with a custom audio file by pointing an environment variable at it.

What is it built with?

ShellSwift

How does it compare?

	foxtrotdev/codex-butler-bell	maxstridde/social_preview	verona136/common-official-document-format-skill
Stars	1	1	1
Language	Shell	Shell	Shell
Setup difficulty	moderate	easy	easy
Complexity	2/5	1/5	2/5
Audience	developer	developer	writer

Figures from each repo's GitHub metadata at analysis time.

How do you get it running?

Difficulty · moderate Time to first run · 5min

Requires Codex with plugins enabled and Xcode CLI tools for the Swift overlay, falls back to sound-only if Swift is unavailable.

Apache 2.0, use freely in personal or commercial projects, the bundled bell sound has a separate Pixabay Content License.

In plain English

Codex Butler Bell is a plugin for Codex, a command-line AI coding assistant. When Codex finishes a task and waits for your permission or response, this plugin plays an animated bell overlay on your screen and a bell sound after a short delay. The goal is to alert you when Codex needs attention without requiring you to watch its terminal window constantly. It is particularly useful if you run several Codex sessions at once or keep Codex hidden behind other windows or on a separate macOS desktop space. The plugin monitors for two events: a permission request (when Codex needs you to approve an action) and a stop event after a response that ends with a question mark. If you do not respond within a configurable delay, the animated bell appears. The overlay itself is a native macOS application written in Swift. It shows a large animated swinging bell and plays a bundled sound file. If Swift is not available on your machine, the plugin falls back to sound-only alerts. Once you respond or the action proceeds, the plugin cancels the pending alert immediately. All settings are controlled through environment variables. You can adjust how long the plugin waits before showing the overlay, how long the overlay stays visible, how fast the bell swings, and the path to a custom sound file if you prefer your own. Everything runs locally with no data sent to any external service. The plugin is installed through Codex's plugin system using two commands, either from a local clone or directly from the GitHub repository. It is licensed under Apache 2.0, with the bundled bell sound covered separately under the Pixabay Content License.

Copy-paste prompts

Prompt 1

I'm running three Codex sessions at once. How does Codex Butler Bell help me know which one needs my attention, and what are the exact install commands?

Prompt 2

How do I configure Codex Butler Bell to wait 30 seconds before showing the overlay and to ring 6 times instead of the default 4?

Prompt 3

What events does Codex Butler Bell listen for, and what is the difference in how it handles a PermissionRequest versus a Stop event?

Prompt 4

Codex Butler Bell is not showing the overlay. Walk me through troubleshooting: check Swift compiler, verify hooks loaded, run the test suite.

Frequently asked questions

What is codex-butler-bell?

A macOS Codex plugin that shows an animated bell overlay and plays a sound when Codex is waiting for your permission or response, useful for monitoring multiple sessions without watching the terminal.

What language is codex-butler-bell written in?

Mainly Shell. The stack also includes Shell, Swift.

What license does codex-butler-bell use?

Apache 2.0, use freely in personal or commercial projects, the bundled bell sound has a separate Pixabay Content License.

How hard is codex-butler-bell to set up?

Setup difficulty is rated moderate, with roughly 5min to a first successful run.

Who is codex-butler-bell for?

Mainly developer.

Open on GitHub → Explain another repo

This repo across BitVibe Labs

Scan in gitsafehub Deploy in gitdeployhub foxtrotdev on gitmyhub

Verify against the repo before relying on details.