Agent Notifier

Install

Install in 30 seconds. No hooks, no uv, no jq.

Four copy-and-paste steps. Works with Claude Code, Codex CLI, Copilot CLI, Cursor, Gemini CLI, or any shell-spawning agent. notify.py is a single stdlib-only Python file — nothing else to install.

  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

    Pick your harness below. Paste the block into the listed file once — your agent will then send proof of work to your iPhone for every milestone.

    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 — event-driven hooks (PreToolUse, PostToolUse, approval gating)

↓

The CLI above is enough for most agents. If you want per-tool-call hook events (PreToolUse approvals, PostToolUse summaries, polling for tap-to-approve responses) you can also install the event-driven hook runner. This requires curl, bash, jq, and uv.

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

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.