Agent Notifier

Setup

Start with notifications. Add live sessions later.

The simple path is one Python file, one API key, and one test push. No hooks, no uv, no jq. When you want live Claude/Copilot tool timelines, use the optional session watcher after notifications work.

Recommended

Simple notifications

Alerts, progress, files, URLs, screenshots, audio, video, and markdown from any script.

Optional

Session watcher

Add hooks for live agent sessions, approvals, tool-call history, and session inboxes.

  1. 1

    Drop notify.py into ~/bin

    One file. Plain Python 3 standard library. Re-run any time to upgrade in place.

    bash
    curl -fsSL https://notifier.aicrew.in/notify.py -o ~/bin/notify.py && chmod +x ~/bin/notify.py

    Make sure ~/bin is on your PATH. If it isn't yet, add export PATH="$HOME/bin:$PATH" to your shell rc file.

    View raw notify.py → · curl-free? wget https://notifier.aicrew.in/notify.py -O ~/bin/notify.py

  2. 2

    Create an account API key

    Sign in once on the web, name your key, copy the secret (shown only once).

    Open app to create a key

    Already signed in? You'll land directly on the API keys panel. Free tier ships with 100 notifications — plenty to wire every harness.

  3. 3

    Save the key in .env.local

    notify.py reads from .env.local in the current repo first, then ~/.config/agent-notifier/config.json. Keep secrets out of shell history.

    .env.local
    # ./.env.local (any project directory)
AGENT_NOTIFIER_API_KEY=an_key_REPLACE_WITH_YOUR_KEY
AGENT_NOTIFIER_PROJECT=my-repo

    Or store globally: ~/bin/notify.py --save-config --api-key an_key_… --project my-repo. Per-project .env.local wins when present.

  4. 4

    Tell your agent to use notify.py

    Optional for notification-only use. Paste the block into the listed file once when you want your agent to send proof of work for milestones.

    Paste into ~/.claude/CLAUDE.md. Append to your global instructions so Claude uses the CLI in every project.

    ~/.claude/CLAUDE.md
    ## Agent Notifier — keep the human updated (notify.py)

Use `~/bin/notify.py` to push real-time updates to the human. Send at task start, major milestones, blockers, and completion. Always include proof:

- File or media artifact: `~/bin/notify.py "Tests passing" --file-path ./logs/proof.png`
- Link out: `~/bin/notify.py "PR ready" --url https://github.com/... --url-title "Open PR"`
- Progress for long runs: `~/bin/notify.py "Migrating database" --type progress --progress 0.5`
- Need a decision: `~/bin/notify.py "Conflict in main" --priority 1 --buttons "Abort" "Manual fix"`

The CLI reads `AGENT_NOTIFIER_API_KEY` + `AGENT_NOTIFIER_PROJECT` from `./.env.local` (preferred) or `~/.config/agent-notifier/config.json`. Never echo the API key. Never send a "task complete" message without attaching the produced artifact.

(Configured for Claude. Run `~/bin/notify.py --help` for the full flag list.)

Verify install

Run this from any directory after Step 3. Your iPhone should light up within a second.

bash
~/bin/notify.py "Hello from $(hostname)" --file-path /etc/hostname

Didn't arrive? Check that the iOS app is installed and signed in, and that your API key is on the active list in the web app.

Advanced — session watcher hooks (PreToolUse, PostToolUse, approvals)

↓

The CLI above is enough for most agents. If you want live agent session timelines (PreToolUse approvals, PostToolUse summaries, polling for tap-to-approve responses) you can also install the session watcher. This requires curl, bash, jq, and uv.

bash
curl -fsSL https://notifier.aicrew.in/install.sh | bash

Prefer a guided page? Open Session watcher setup.

Set AGENT_NOTIFIER_API_KEY in your environment before running. The installer writes .github/hooks/hooks.json and .claude/settings.json for the current repo, never commits the key, and appends a project-local CLAUDE.md reminder.

Source: github.com/yashness/agent-notifier/hooks.