Metadata-Version: 2.4
Name: codex-bell
Version: 0.1.2
Summary: Beep when OpenAI Codex finishes a task or needs your input.
License-Expression: MIT
Project-URL: Homepage, https://github.com/kevod1997/codex-bell
Project-URL: Repository, https://github.com/kevod1997/codex-bell
Project-URL: Bug Tracker, https://github.com/kevod1997/codex-bell/issues
Keywords: openai,codex,cli,notification,productivity
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# codex-bell

[![PyPI](https://img.shields.io/pypi/v/codex-bell)](https://pypi.org/project/codex-bell/)
[![Python](https://img.shields.io/pypi/pyversions/codex-bell)](https://pypi.org/project/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

```bash
pip install codex-bell
```

Then just run:

```bash
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]
```

| Flag | Description |
|---|---|
| `--path PATH` | One-off override for the sessions directory |
| `--interval N` | Polling interval in seconds (default: 2) |
| `--reconfigure` | Forget saved path and prompt again |

---

## 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 three events**: `task_complete`, `request_user_input`, and `require_escalated`.
3. **Fires a beep** using the best available method for your OS (see table below).

---

## Compatibility

| OS | Beep method |
|---|---|
| Windows | `winsound.Beep` (built-in) |
| macOS | `afplay /System/Library/Sounds/Glass.aiff` |
| Linux | `paplay` → `aplay` → ANSI terminal bell (fallback chain) |
| Other | ANSI terminal bell (`\a`) |

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
