codex-notifier

Tiny macOS notifier binary for OpenAI Codex (Rust) that plugs into Codex’s built‑in notify hook. When Codex emits events (e.g., end of a model turn), this tool shows a Notification Center banner and optionally plays a system sound.

Why

• Get an audible/visual ping when it’s your turn to act.
• No external daemon. No polling. Codex calls your binary directly per event.
• Zero runtime deps (uses macOS osascript + afplay).

Features

• Notification Center banner via AppleScript (osascript).
• Optional sound using system sounds via afplay (e.g., Glass, Submarine).
• Configurable title/sound through CLI flags or your Codex config.
• Parses Codex’s notify JSON; currently shows message on agent-turn-complete.

---

Install

Prereqs: macOS, Rust (cargo).

# From this repository
cargo install --path .
# The binary will be placed at: ~/.cargo/bin/codex-notifier

Or use the provided Makefile to build, install, and wire Codex automatically:

make setup
# Builds and installs, then configures ~/.codex/config.toml

Customize sound/title during setup:

make setup SOUND=Submarine TITLE="Codex"

---

Wire into Codex (Rust CLI)

Codex (Rust) supports a notify hook in ~/.codex/config.toml. Add:

notify = ["/Users/you/.cargo/bin/codex-notifier", "--sound", "Glass", "--title", "Codex"]

With the Makefile, this is done for you:

make configure              # (re)writes notify entry
make uninstall              # removes notify entry and uninstalls binary

---

How it works (Codex notify JSON)

Codex invokes your command with one JSON argument (argv[1]). This tool expects a payload like:

{
  "type": "agent-turn-complete",
  "last-assistant-message": "All tests passed",
  "input-messages": ["run unit tests"]
}

Behavior:

• When type == "agent-turn-complete", it shows a banner with last-assistant-message (fallback: "Codex turn complete") and plays the configured sound.
• Other event types are displayed generically as Codex event: <type> (plays sound too).

You can extend behavior by adding more matches in src/main.rs.

---

Usage

Run manually for a quick test (no Codex needed):

~/.cargo/bin/codex-notifier \
  --sound Glass \
  --title "Codex" \
  '{"type":"agent-turn-complete","last-assistant-message":"All tests passed"}'

Flags:

• --sound <NAME>: System sound name (default: Glass). Use macOS sounds, e.g., Glass, Submarine, Pop.
• --title <TEXT>: Notification title (default: Codex).

---

Makefile targets

make build        # cargo build --release
make install      # cargo install --path .
make configure    # write notify entry to ~/.codex/config.toml (backs up existing)
make setup        # build + install + configure
make test         # send a test notification
make uninstall    # remove notify entry and binary

Notes:

• The configure step removes any existing notify = [...] block (single or multi‑line) before writing the new line.
• A backup of your Codex config is written next to it (timestamped).

---

Development

# Edit
$EDITOR src/main.rs

# Build & run a test payload
cargo run -- \
  --sound Glass \
  '{"type":"agent-turn-complete","last-assistant-message":"Dev build ping"}'

Implementation details:

• Notifications use AppleScript:
  • osascript -e 'display notification "..." with title "..."'
• Sound playback prefers /usr/bin/afplay /System/Library/Sounds/<NAME>.aiff.
  • If afplay fails, it attempts terminal-notifier -sound <NAME> if present.
• No background processes; Codex triggers the binary per event.

Extending

Add new matches in src/main.rs for additional type values Codex may emit, and derive the message you want to display (e.g., show counts, durations, summaries).

---

Troubleshooting

• No banner appears:
  • Confirm Notification Center isn’t set to Do Not Disturb.
  • Try a simple AppleScript: osascript -e 'display notification "Ping" with title "Test"'.
• No sound:
  • Try a different sound: Glass, Submarine, Pop (must exist in /System/Library/Sounds/).
• Codex not calling the binary:
  • Verify your ~/.codex/config.toml has the notify = [...] line and the path is correct/executable.

---

License

Apache-2.0

---

Acknowledgements

• OpenAI Codex CLI (Rust) notify hook design.
• macOS AppleScript/Notification Center.