macOS notifications with sound and voice alerts for agent CLIs.

The repository still ships the original Claude Code plugin, and now also includes a dedicated Codex adapter. They live in one repo, but each environment keeps its own entrypoint and installation flow.

When the adapter fires, you get:

1. Desktop notification via terminal-notifier (with Submarine sound) when available
2. Audio alert with Basso
3. Voice announcement with the session label

The spoken label is environment-specific. For Codex, the voice says Codex terminou em {label} (or Codex terminou no app for the Codex macOS App). For Claude, the existing Claude Code {label} behavior is preserved.

• macOS
• afplay
• say
• osascript
• terminal-notifier

brew install terminal-notifier

The Claude adapter stays backward-compatible with the existing plugin layout.

From a local directory:

claude plugin install /path/to/claude-code-notify

From GitHub:

claude plugin install github:robertoecf/claude-code-iterm-notify

Restart Claude Code after installing or updating. Claude loads hooks at session start.

The plugin registers two Notification hooks:

• permission_prompt
• idle_prompt

Both still call hooks/scripts/notify.sh. That path is now a shim that delegates to adapters/claude/notify.sh, so older setups do not break.

echo '{"message":"test","title":"Claude Code"}' | bash hooks/scripts/notify.sh

Codex does not use the Claude plugin system. The supported integration point is the notify command in ~/.codex/config.toml.

Copy the adapter to your Codex bin directory:

bash adapters/codex/install.sh --install-script ~/.codex/bin/codex-notify.sh

bash adapters/codex/install.sh --print-config ~/.codex/bin/codex-notify.sh

Expected output:

notify = ["/Users/you/.codex/bin/codex-notify.sh"]

Then add that line to ~/.codex/config.toml.

Run the adapter in dry-run mode:

bash adapters/codex/install.sh --self-test ~/.codex/bin/codex-notify.sh

Or invoke the repository script directly:

NOTIFY_TEST_MODE=1 bash adapters/codex/notify.sh \
  '{"type":"agent-turn-complete","cwd":"/tmp/example","last-assistant-message":"notifier pronto"}'

Codex exposes exactly one event to the notify hook: agent-turn-complete. Approval requests, input requests, exec-approval, and patch-approval events all travel on different channels and never reach this script — see openai/codex#11808 and protocol source.

So the adapter is deliberately minimal:

• On every agent-turn-complete, it fires a short voice announcement Codex terminou em <label> (or Codex terminou no app for the Codex macOS App).
• The desktop notification shows the first ~160 characters of the last assistant message as a preview.
• Identical events within 30 s (same label+message) are suppressed via a cooldown file.
• The adapter does not read the assistant response aloud — that was the source of noise. Glance at the notification or the terminal/app for the actual content.

Because Codex does not send those signals to the notify hook, use the right layer for each environment:

Codex macOS App — enable approval-request notifications in the app preferences. The app delivers them natively through macOS notifications.

Codex CLI (TUI) — add to ~/.codex/config.toml:

[tui]
notifications = ["agent-turn-complete", "approval-requested"]
notification_method = "osc9"

The terminal (iTerm2, Ghostty, Terminal.app) then emits native desktop notifications via OSC 9 when Codex asks for approval. See Advanced configuration.

Fully custom behavior — the only way to react to every EventMsg in the adapter itself is to consume Codex as an MCP server (codex mcp) instead of via the one-shot notify hook. That is out of scope for this repo today.

The Codex adapter resolves the label in this order:

1. iTerm2 profile name when ITERM_SESSION_ID is available
2. Codex App process ancestry when the script is launched from the macOS app
3. normalized terminal name from TERM_PROGRAM
4. basename of the cwd in the Codex payload
5. Codex

This keeps multiple tabs distinguishable without hardcoding agent names into the voice message.

The adapter now resolves these environments explicitly:

• Ghostty → Ghostty
• iTerm2 → profile name when available, otherwise iTerm2
• Apple_Terminal → Terminal.app
• vscode → VS Code
• Codex macOS App process tree → Codex App

If you run multiple Claude or Codex sessions in iTerm2, create named profiles such as 1, 2, api, or review.

When a session needs attention, the voice will use the profile name when it can be resolved. That is the cleanest way to identify parallel sessions.

.
├── adapters
│   ├── claude
│   │   └── notify.sh
│   └── codex
│       ├── install.sh
│       └── notify.sh
├── hooks
│   ├── hooks.json
│   └── scripts
│       └── notify.sh
└── tests
    └── codex_notify_test.sh

Run the Codex adapter regression test:

./tests/codex_notify_test.sh

• Restart Claude Code
• Check ~/.claude/settings.json for invalid configuration
• Test hooks/scripts/notify.sh manually

• Confirm notify in ~/.codex/config.toml points to the right script
• Confirm the script receives the payload as an argument
• Use NOTIFY_TEST_MODE=1 to inspect parsed output without sending desktop notifications

That is expected. Codex notify is configured through config.toml, and the current documented external notification event is agent-turn-complete. This repository keeps adapters separate so each environment can use the signals it actually exposes.

MIT — see LICENSE.