How can an AI agent send me a push notification?

An AI agent can notify you the same way any script can: with one HTTP POST to a notification API, authenticated by a scoped key. If your agent speaks the Model Context Protocol (MCP), you can go a step further and hand the model a notification tool it calls on its own, so it decides when a human needs to know something. Pair either path with a heartbeat monitor and you also learn when the agent stops running entirely — silence becomes an alert instead of a mystery.

Why do autonomous agents need a notification path?

The whole point of an autonomous agent is that you are not watching it. A coding agent refactors a repository while you make dinner; a research agent grinds through a queue overnight; a scheduled agent run kicks off from cron at 6am. The moment you stop supervising, three questions appear that a terminal scrollback cannot answer from your phone:

• Did it finish? A run that takes forty minutes should not require forty minutes of glancing at a terminal.
• Is it blocked? Agents routinely hit a decision they should not make alone — a destructive migration, an ambiguous requirement, a failing test they want to delete. Blocked silently is the worst state: you think work is happening and it is not.
• Did it die? A crashed process sends nothing, which looks exactly like a process that is still working.

Email answers none of these well — it is slow, batched, and buried. What you want is the same thing you want from a failing cron job: a push notification on your phone within seconds, in a channel you can mute or prioritize. The plumbing turns out to be almost identical to sending a push notification from a bash script, because to your notification layer, an agent is just a very talkative script.

Option 1: one HTTP call at the end of the run

Every serious agent framework can either run a shell command or make an HTTP request. That means the simplest integration is zero-framework: tell the agent (in its system prompt, task instructions, or a wrapper script) to run one command as its final step.

curl -X POST https://pingwire.dev/api/v1/messages.php \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel":"agents","title":"Refactor complete","text":"42 files changed, test suite green. Two TODOs left for review.","priority":"high"}'

The message lands in a real-time chat channel and as web push on your phone. A few details that matter more for agents than for ordinary scripts:

• Give each agent its own channel (agents, overnight-research, ci-fixer). You can mute a noisy experiment without muting the agent you actually care about.
• Use title for the verdict and text for the detail. On a lock screen you may only see a few words — make them the words that decide whether you pick up the phone.
• Use priority honestly. "Run finished" is normal. "Run blocked awaiting approval" is high. If everything is urgent, nothing is.
• Prefer a wrapper over trusting the model to remember. A shell wrapper that runs the agent and then reports its exit status will fire even when the model forgets its instructions or the process is killed: run-agent.sh && notify "done" || notify "FAILED".

This works today with Claude Code hooks, cron-launched agent scripts, CI-triggered agents — anything with a shell. No SDK required; it is one HTTP call.

Option 2: give the model a notification tool over MCP

The HTTP approach notifies at boundaries you predicted: end of run, on failure. The Model Context Protocol moves the decision into the run. MCP is an open standard that lets an AI application expose tools to the model; give the model a send notification tool and it can ping you at the moment something becomes worth saying — halfway through, when it discovers the real problem is different from the assigned one, or when it wants permission before doing something irreversible.

Pingwire ships an MCP server, documented in the MCP integration docs, whose tools let an agent send to a channel and even create subscribe-by-scan QR channels on the fly. Wiring it into an MCP-capable client is a small JSON config entry pointing at the server with your API key in the environment — the docs page has the exact snippet for the client you use.

The practical difference between the two options is judgment. A curl command fires when your script says so; an MCP tool fires when the model judges a human should know. The best setups use both: MCP for mid-run judgment calls, plus a wrapper-level notification the model cannot forget.

How do I find out when my agent crashes instead of finishing?

Neither option above covers the failure mode that actually bites: the agent that stops existing. A killed process, an expired credential, an OOM, a machine that rebooted — none of these run your final curl. The fix is the same dead man's switch pattern used for cron jobs: invert the signal, so the alarm is silence.

Create a heartbeat monitor with a period matching your agent's cadence (say, one check-in expected per loop iteration or per scheduled run), then have the run report that it is alive:

# end of each successful iteration or run
curl -fsS --retry 3 https://pingwire.dev/hb/YOUR-TOKEN > /dev/null

# or branch on failure to open an incident immediately
./run-agent.sh && curl -fsS https://pingwire.dev/hb/YOUR-TOKEN \
            || curl -fsS https://pingwire.dev/hb/YOUR-TOKEN/fail

If the monitor does not hear a check-in within the period plus a grace window, it opens an incident and pushes your phone. The agent does not need to be healthy enough to report failure — that is the entire point. This is the same inversion we covered for websites in how to get notified when your website goes down: the dangerous failures are the quiet ones.

Patterns that hold up in practice

The end-of-run summary

One message per run: what was attempted, what changed, what needs human review. Resist the temptation to stream progress — a notification per step trains you to ignore the channel, and an agent that sends forty messages has effectively sent none. As a backstop, machine senders that repeat identical text within a short window are collapsed into one message, so a retrying wrapper will not spam you — but design for one good summary rather than relying on dedupe.

The approval gate

Before a destructive or expensive step, have the agent send a high-priority message describing exactly what it wants to do, then pause. Because messages land in a two-way chat rather than a fire-and-forget popup, your reply is right there in the channel, and an agent that can read the channel (the messages API supports listing recent messages) can poll for your answer before proceeding. Human-in-the-loop without a custom UI.

Error-only alerting for scheduled agents

For agents that run on a schedule and usually succeed, flip the default: heartbeat on success, message only on failure. Your phone stays quiet until quiet is wrong.

Scheduled follow-ups

When an agent defers work — "rate limited, will need a retry after the window resets" — it can schedule the reminder itself with one call to the reminders API (run_at for one-off, cron for recurring), so the follow-up pings you even if the agent never runs again.

What to avoid

• Do not put secrets in message bodies. Agents love to be helpful and paste environment details. Tell them explicitly, in the same instruction that grants the notification tool, never to include tokens, keys, or credentials in a message.
• Do not share one key across all agents. Issue a scoped key per agent. When you retire an experiment — or an agent goes haywire — you revoke one key and everything else keeps working.
• Do not let the model be the only reporter. Models forget instructions under long contexts. The wrapper-plus-heartbeat combination reports even when the model does not.
• Do not page yourself for progress. Notify on outcomes, blocks, and failures. Everything else belongs in a log.

Where to start

Start with option 1: create an API key, add the one-line curl to whatever launches your agent, and confirm the push arrives on your phone. Add a heartbeat monitor the first time an agent dies silently on you (it will). Reach for MCP when you find yourself wanting the agent to ask permission mid-run. The full endpoint reference, with copy-paste examples in several languages, lives in the developer docs.