codex-bell

Get a beep when OpenAI Codex finishes a task or needs your input.

The problem

Codex runs tasks in the background and goes silent for minutes at a time. You end up tab-switching constantly just to check whether it's done — or you miss the moment it asks for input and the whole session stalls.

codex-bell watches your Codex session logs and fires a system beep the instant something needs your attention.

Install

pip install codex-bell

Then just run:

codex-bell

On first run, codex-bell looks for ~/.codex/sessions (the default path used by the Codex CLI on all platforms). If it can't find it, it will ask you where your sessions are and save the answer so you never have to type it again.

Usage

codex-bell [--path PATH] [--interval SECONDS] [--reconfigure] [--verbose]

How it works

1. Tails .jsonl files under your Codex sessions directory by tracking byte offsets — only new content is read on each poll.
2. Detects five events: task_complete, request_user_input, require_escalated, apply_patch_approval, and exec_approval_request.
3. Fires a beep using the best available method for your OS (see table below).

Compatibility

No external dependencies. Pure Python standard library + subprocess.

Why I built it

I was running long Codex sessions and kept missing the moment they finished — or the moment Codex stopped and waited for me. A proper notification felt like too much; I just wanted a beep. Spent an afternoon turning a quick winsound hack into something cross-platform and pip-installable.

Design note: polling vs. filesystem events

codex-bell polls every 2 seconds instead of using filesystem event APIs (like inotify on Linux or FSEvents on macOS). This was intentional:

• Zero dependencies — no C extensions, no watchdog, no install pain.
• Dead simple — one timer loop, easy to reason about.
• Good enough — 2-second latency is imperceptible for "your agent finished a multi-minute task."

If you need sub-second reaction time, swap the loop in watcher.py for watchdog. For the use case this tool was built for, polling is the right call.

License

MIT © Kevin Defalco