# Set up Agent Alerts

This document is an instruction for the AI agent reading it: continue the setup
below. Do not ask the user to choose a task, and do not treat missing
agentalerts_* MCP tools as a blocker.

Human setup: https://andreas.ink/agent
Canonical agent instructions: https://andreas.ink/agent/instructions

Agent Alerts keeps long-running agent and automation work visible on an iPhone
through evolving Live Activities.

## Default route: HTTPS webhook

Use the webhook for Claude, Codex, Cursor, hosted agents, CI, and other
automation runtimes unless the user explicitly asks for the local Mac MCP
integration or an existing workflow already depends on it.

Human steps:

1. Install Agent Alerts on iPhone and sign in.
2. Open https://andreas.ink/agent on the runtime's computer.
3. Complete verification, name the runtime, and create the pairing request.
4. Scan the QR code in Agent Alerts, compare the matching code, and approve
   publish-only access.
5. Copy the one-time setup key directly into the runtime's secret manager as
   AGENTALERTS_AGENT_TOKEN. For local Claude Code or Codex, the designated
   durable location may be ~/.config/agent-alerts/token.env with mode 0600.
   Enter it outside the AI conversation; never paste it into the AI chat.

Agent steps:

1. Install the public Agent Alerts skills from
   https://github.com/AndreasInk/AgentAlertsSkill.
2. Use $agent-alerts-setup to define the alert contract. The webhook is already
   the selected route.
3. Check only whether AGENTALERTS_AGENT_TOKEN is available; never print its
   value.
4. Before enabling a schedule, resolve the exact installed
   agent-alerts-execution/scripts/send_webhook.sh path. Give only that command
   persistent permission. Do not grant Claude direct Read access to the token
   directory; the helper safely reads the designated token file itself.
5. Create the JSON payload with the runner's file-write tool as a separate
   action. Do not use a Bash heredoc, shell redirection, or a compound command
   that also invokes the helper.
6. Run the helper as one standalone command with --check-config from the real
   automation context. Repeat until it succeeds without any approval prompt.
7. Run an idempotent smoke send through the same command. If a one-time network
   approval appears, make the narrow rule persistent and repeat with the same
   Idempotency-Key. The repeated send must complete without a prompt.
8. Send HTTPS POST requests to:

   https://bsakakesupfudupbxflj.supabase.co/functions/v1/agentalerts-webhook

9. Send the token only as an Authorization: Bearer header. Use a stable
   activityId with updateMode "upsert_single" and a fresh Idempotency-Key for
   each changed event.
10. If the user requested a smoke test, send one non-sensitive test through
   $agent-alerts-execution and report server/APNs acceptance separately from
   visible-device confirmation.

If either the payload check or repeated smoke send still needs interaction, do
not schedule the automation. Report AGENTALERTS_SCRIPT_NOT_AUTHORIZED.

Agent Alerts is the delivery channel, not the scheduler. Unless the user
explicitly requests an ephemeral reminder, do not use a Claude session-only
cron, sleeping shell, or timer that stops when the current session closes.
Choose a durable scheduler such as a Codex automation, launchd, system cron,
CI, or another persistent runner. If none is available, report
AGENTALERTS_SCHEDULER_NOT_DURABLE.

Webhook reference: https://andreas.craft.me/6KEDmLqGXVDJx0

## Optional route: local Mac MCP

Use local MCP only when the user explicitly wants a desktop-local integration.
It requires the Agent Alerts macOS beta and generated client configuration.

1. Install and open the Agent Alerts macOS beta.
2. Approve the discovered Mac from the iPhone app.
3. In the Mac app, choose the AI client and copy its generated MCP setup command
   or configuration.
4. Restart the AI client and confirm agentalerts_status and agentalerts_send are
   available.

Mac setup guide: https://andreas.craft.me/CqENhaW2l9YP1g
macOS beta: https://github.com/AndreasInk/AgentAlertsSkill/releases/tag/beta

## Skills and security

Repository: https://github.com/AndreasInk/AgentAlertsSkill
Setup skill: https://github.com/AndreasInk/AgentAlertsSkill/blob/main/agent-alerts-setup/SKILL.md

Use $agent-alerts-setup while designing or revising delivery. Use
$agent-alerts-execution only when a run is ready to send or skip.

Never paste an Agent Alerts token into a chat, prompt, URL, command line, log,
source file, or receipt. Give each runtime its own revocable publish-only token.