Area.mp4
Tired of switching back to Codex only to realise it’s been waiting on your input? CodexPing is a small macOS status app that keeps a floating overlay in sync with Codex activity.
Free to use! The only condition is that you leave a star on the repo ⭐️
It listens to the status of your Codex chat and shows one of four states:
WorkingNeeds InputDoneIdle
When the app is configured correctly, the overlay appears across spaces and updates automatically as Codex runs.
- Floating always-on-top overlay that works across macOS Spaces
- One-click setup installer for the required Codex hook configuration
- Animated visuals for each state
- Audible chime when Codex is done or awaiting input.
- Fades out when unused
- macOS
- Xcode
- Codex installed locally
- Download the latest .dmg release.
- Drag into your Applications folder.
- Clone this repository.
- Open
CodexPing.xcodeprojin Xcode. - Select the
CodexPingscheme. - Build and run the app.
When the app launches, it checks whether Codex hooks are set up.
If setup is incomplete, open the app, select the your .codex directory (usually in ~/.codex) and use Install Recommended Setup. This will:
- enable codex hooks
- write or update
~/.codex/hooks.jsonwith the recommended status hooks
- Launch CodexPing.
- Confirm the setup screen shows all requirements as satisfied.
- Start a Codex session.
- Watch the overlay update as Codex moves through working, waiting for input, and finishing.
The overlay stays visible only when setup is complete. If hooks are missing, the setup screen is shown instead.
Contributions are welcome. A good workflow is:
- Open an issue or describe the change you want to make.
- Make the change in a small, focused branch.
- Add or update tests where it makes sense.
- Verify the app still builds and the UI behaves correctly.
If you plan to contribute code, please keep the overlay behavior and setup flow aligned with the existing app design.
Created by Kane Testa.