AgentNotifier

When you step away from your keyboard, Codex or Claude can get blocked waiting for approval/input and your flow stalls. AgentNotifier sends those moments to your phone (and optionally macOS) through ntfy, so you can return only when needed.

It covers action-needed, finished, and failed events for both tools.

Codex integration is macOS-only. Claude integration works on macOS and Linux.

Try in 60 seconds

If pipx is missing, install it first:

python3 -m pip install --user pipx
python3 -m pipx ensurepath

Then restart your shell and run:

pipx install "git+https://github.com/almuqrin/agentnotifier.git@v0.1.1"
agentnotifier claude
agentnotifier test

Expected result:

• Setup prints a subscribe on phone/mac: URL.
• After you subscribe in the ntfy app, agentnotifier test sends a test notification.

If you use Codex on macOS, also run:

agentnotifier codex

Who this is for

• You use Codex or Claude Code daily.
• You leave your keyboard often and miss prompts.
• You want simple push notifications without a heavy integration.

Who this is not for

• You need a fully managed hosted service.
• You need guaranteed long-term support.
• You do not want to install and configure ntfy.

What it covers

• Codex: needs approval, needs input, finished, failed
• Claude: action-needed Notification, plus Stop and SubagentStop
• Delivery: ntfy push plus optional local macOS notifications

Commands

agentnotifier claude
agentnotifier codex                # macOS only
agentnotifier remove claude
agentnotifier remove codex         # macOS only
agentnotifier test
agentnotifier doctor

agentnotifier doctor runs local diagnostics for config, hooks, and platform-specific setup.

Requirements

• Python 3.10+
• ntfy app on phone and/or macOS
• macOS for Codex daemon management and local desktop notifications

Installation notes

• Recommended for daily use (installed command on your PATH):

python3 -m pip install --user pipx
python3 -m pipx ensurepath
# restart your shell
pipx install "git+https://github.com/almuqrin/agentnotifier.git@v0.1.1"

• The pipx run --spec ... method above is best for quick trials.

Config and file locations

• Config: ~/.config/agentnotifier/config.json
• Codex daemon state: ~/.local/state/agentnotifier/codex_state.json
• Claude settings touched by install/remove: ~/.claude/settings.json
• Optional token environment variable: NTFY_TOKEN

To rotate the generated topic, remove ~/.config/agentnotifier/config.json and run agentnotifier claude (or agentnotifier codex) again.

Troubleshooting

pipx: command not found

python3 -m pip install --user pipx

Then use python3 -m pipx ... commands directly, or run python3 -m pipx ensurepath and restart your terminal if you want the pipx command on PATH.

No phone notification

• Confirm you subscribed to the exact URL shown by setup.
• Run agentnotifier test and verify network access to your ntfy server.
• Run agentnotifier doctor and fix any FAIL results.

No macOS notification

• Confirm notifications are enabled for your terminal app.
• Confirm osascript exists on your system.
• Run agentnotifier doctor to validate local notification prerequisites.

Codex daemon not running

• Re-run agentnotifier codex and check the printed Plist: path.
• If ~/Library/LaunchAgents is not writable, AgentNotifier automatically falls back to ~/.local/state/agentnotifier/com.agentnotifier.codex.plist.
• Check service status: launchctl print gui/$UID/com.agentnotifier.codex

CERTIFICATE_VERIFY_FAILED when publishing to ntfy

• On python.org macOS builds, run Install Certificates.command.
• Or install certifi and set SSL_CERT_FILE="$(python -m certifi)", then retry.

Claude events not triggering

• Re-run agentnotifier claude.
• Check ~/.claude/settings.json for command hooks on Notification, Stop, and SubagentStop.
• Run agentnotifier doctor to confirm managed Claude hooks are present.

Development

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e ".[dev]"
python -m ruff check .
python -m ruff format --check .
python -m pytest

Project status

This is a vibecoded, AI-generated personal workflow project shared as-is. Changes are usually accepted based on working behavior rather than line-by-line review. There is no telemetry.

See AI_DISCLOSURE.md for details.

Project notes

• Report bugs through GitHub Issues.
• Report security concerns through private GitHub contact.
• Release history: CHANGELOG.md

License

MIT