{"documents":[{"id":"agent-alerts-pricing","kind":"pricing","path":"pricing","url":"https://www.andreas.ink/agent-alerts/pricing","markdownUrl":"https://www.andreas.ink/api/agent-alerts/content?path=pricing&format=markdown","title":"Agent Alerts pricing","description":"Start free. Choose Pro monthly, yearly, or lifetime in the iPhone app.","keywords":["Agent Alerts","pricing","price","cost","Free","Pro","subscription","limits","USD"],"content":"# Agent Alerts pricing\n\nDownload Agent Alerts on iPhone. Start free and upgrade to Pro in the app.\n\n## Free\n\n- $0. 350 delivered alert events per UTC day.\n- 1 widget.\n\n## Pro\n\n- 3,500 delivered alert events per UTC day.\n- Interactive responses with the required connection permissions.\n- Monthly: $3.99 per month.\n- Yearly: $29.99 per year.\n- Lifetime: $59.99 one-time purchase.\n\nUS App Store prices in USD. Local pricing and purchase terms appear in the app.\nA delivered event targeting both a Live Activity and a notification counts once. Widget-only refreshes do not consume the delivered-alert allowance.\nYour AI client runs the work and accesses the tools you authorize. Agent Alerts shows the results it sends.\n\n[Download on the App Store](https://apps.apple.com/us/app/agent-alerts/id6760969938)\n[Read the docs](https://www.andreas.ink/agent-alerts/docs)"},{"id":"agent-alerts-doc-getting-started","kind":"doc","slug":"getting-started","title":"Send your first update.","description":"Connect an AI client or a script, then confirm the result on your iPhone.","keywords":["Agent Alerts","setup","quickstart","install","first update"],"updatedAt":"2026-11-10","content":"# Send your first update.\n\nConnect an AI client or a script, then confirm the result on your iPhone.\n\n## 1. Install Agent Alerts\n\n[Download Agent Alerts on the App Store](https://apps.apple.com/us/app/agent-alerts/id6760969938), open it on your iPhone, and finish onboarding. Sign in with the account you will connect to your AI client and allow the notifications you want to receive.\n\nYour AI client runs the work and accesses your authorized tools. Agent Alerts shows the results it sends. Connecting Agent Alerts alone does not start checks or create a recurring schedule.\n\n## 2. Choose a connection\n\n- [Remote MCP](/agent-alerts/docs/remote-mcp) connects ChatGPT, Codex, Claude, and Cursor through account sign-in.\n- [Swift CLI](/agent-alerts/docs/swift-cli) sends prepared updates from macOS terminal workflows and scripts.\n- [Webhook API](/agent-alerts/docs/webhook-api) accepts HTTPS requests from services and unattended workflows.\n\nUse remote MCP when your AI client supports it. Use the CLI or webhook when your workflow needs a scoped publishing token instead of browser sign-in.\n\n## 3. Check your iPhone\n\nAsk for one short, non-sensitive test update. Check both the returned result and your iPhone: an accepted request does not confirm visible delivery.\n\nAfter [CLI setup](/agent-alerts/docs/swift-cli), download [funnel.json](/agent-alerts/examples/funnel.json) into your terminal's current folder and try the gallery example:\n\n```bash\nagentalerts send --file funnel.json --activity-id funnel\n```\n\nThis example sends a Live Activity and a notification. Its values are illustrative sample data.\n\n## Keep one result current\n\nReuse one activity ID for updates about the same work. Change the summary, measured values, or next step when there is something useful to report. Choose notification and escalation behavior with the user before adding it to a workflow.\n\n[Explore the Live Activity examples](/agent-alerts/docs/live-activity-examples) or [read about updating one activity](/agent-alerts/blog/keep-one-live-activity-current).\n\n## Read with an agent\n\nThese docs, [pricing](/agent-alerts/pricing), and the [blog](/agent-alerts/blog) are public. An agent can read a page without signing in, fetch its Markdown or JSON from the [content API](/api/agent-alerts/content), or search the [site index](/api/search-index).\n\nFor read-only MCP access to the published content, connect:\n\n```text\nhttps://www.andreas.ink/api/agent-alerts/content/mcp\n```\n\nThis knowledge server reads public content. To send alerts to your own iPhone, connect the separate [Agent Alerts remote MCP](/agent-alerts/docs/remote-mcp).\n","path":"docs/getting-started","url":"https://www.andreas.ink/agent-alerts/docs","markdownUrl":"https://www.andreas.ink/api/agent-alerts/content?path=docs%2Fgetting-started&format=markdown"},{"id":"agent-alerts-doc-remote-mcp","kind":"doc","slug":"remote-mcp","title":"Remote MCP","description":"Connect ChatGPT, Codex, Claude, or Cursor to send Agent Alerts through account sign-in.","keywords":["Agent Alerts","MCP","ChatGPT","Codex","Claude","Cursor","OAuth","connect"],"updatedAt":"2026-11-10","content":"# Remote MCP\n\nConnect ChatGPT, Codex, Claude, or Cursor to send Agent Alerts through account sign-in.\n\nConnect an AI client to Agent Alerts through account sign-in. Your client can then send updates to the iPhone signed in with that account.\n\n## Before connecting\n\nInstall [Agent Alerts](https://apps.apple.com/us/app/agent-alerts/id6760969938), finish onboarding, and sign in on your iPhone. Make sure your AI client supports remote HTTP MCP connections and browser authentication.\n\n## Add the server\n\nUse this endpoint for sending alerts:\n\n```text\nhttps://www.andreas.ink/api/agent/mcp\n```\n\nFor a guided connection flow, open [MCP setup](/agent/mcp).\n\n### Codex\n\n```bash\ncodex mcp add agent-alerts --url https://www.andreas.ink/api/agent/mcp\ncodex mcp login agent-alerts --scopes openid,email,profile,offline_access\n```\n\n### Claude Code\n\n```bash\nclaude mcp add --transport http --scope user agentalerts https://www.andreas.ink/api/agent/mcp\n```\n\nThen open Claude Code, run `/mcp`, and follow the browser sign-in flow.\n\n### ChatGPT, Claude, and Cursor\n\nAdd a custom remote HTTP MCP connection in the client's connector or MCP settings. Paste the endpoint above, then follow its browser authentication flow. Client names and settings can differ by version; [MCP setup](/agent/mcp) links to each client's official instructions.\n\n## Sign in and test\n\nUse the same account as your iPhone and review the access request before approving it. Ask the client to check Agent Alerts status, then send a non-sensitive test update.\n\nFor example:\n\n```text\nCheck my Agent Alerts connection. Send one test update saying that setup is ready, then tell me the returned delivery status. I will confirm it on my iPhone.\n```\n\nAn accepted request is not proof that the Live Activity or notification appeared. Confirm the result on the phone before relying on the connection.\n\n## Agree on the workflow\n\nTell your agent what to check, which sources it may use, when to refresh, and what needs a notification. Reuse a stable activity key for the same subject. The AI client owns checks and recurring schedules; Agent Alerts receives the updates.\n\nAlarms require an explicit user request. A pending or expired response is not permission to take an action. See [responses and permissions](/agent-alerts/docs/responses-and-permissions).\n\n## Need an unattended connection?\n\nFor a service that cannot complete browser authentication, use an iPhone-approved publishing token with the [webhook API](/agent-alerts/docs/webhook-api) or [Swift CLI](/agent-alerts/docs/swift-cli). Keep the token in the runtime's secret storage.\n\nThe [public docs MCP](/agent-alerts/docs#read-with-an-agent) is a separate, read-only knowledge connection. It does not sign you in or send alerts.\n","path":"docs/remote-mcp","url":"https://www.andreas.ink/agent-alerts/docs/remote-mcp","markdownUrl":"https://www.andreas.ink/api/agent-alerts/content?path=docs%2Fremote-mcp&format=markdown"},{"id":"agent-alerts-doc-swift-cli","kind":"doc","slug":"swift-cli","title":"Swift CLI","description":"Install the Swift CLI with Homebrew and send updates from macOS terminal workflows.","keywords":["Agent Alerts","CLI","Homebrew","macOS","terminal","hooks","install"],"updatedAt":"2026-11-10","content":"# Swift CLI\n\nInstall the Swift CLI with Homebrew and send updates from macOS terminal workflows.\n\nUse the Swift CLI to send Agent Alerts from terminal workflows and scripts on macOS 13 or later.\n\n## Install with Homebrew\n\n```bash\nbrew tap andreasink/agent-alerts-cli https://github.com/AndreasInk/agent-alerts-cli.git\nbrew install andreasink/agent-alerts-cli/agentalerts\nagentalerts setup\n```\n\nSetup opens the website pairing flow. Review the requested access, scan its QR code with Agent Alerts on iPhone, compare the code on both devices, and approve the connection.\n\nPaste the one-time token into the CLI's hidden prompt. Store tokens only in the secret storage for the runtime that sends your updates. Do not put tokens in commands, source code, logs, or conversations. Token plaintext is shown once; if it is lost, revoke that connection and create a replacement.\n\n## Send the first example\n\nDownload [funnel.json](/agent-alerts/examples/funnel.json) into your terminal's current folder, then run:\n\n```bash\nagentalerts send --file funnel.json --activity-id funnel\n```\n\nThis uses the gallery's activation funnel sample, with illustrative values of 100%, 72%, 58%, and 41%. The example sends a Live Activity and notification. Check the command result and confirm what appeared on your iPhone.\n\n## Update the same activity\n\nUse the same `--activity-id` for the same subject. Replace the file's content with the next observed result, then send again. Keep different workflows on different stable IDs.\n\nBuilder content files use `builderSpec` and `data`. Gallery downloads already use the Swift CLI's supported content format. The remote MCP example request beside an image may use a different request shape; do not treat it as a CLI content file.\n\n## Hooks and automation\n\nThe CLI repository includes hooks and integration instructions. Choose an event that matches the claim you want to report: an agent turn ending does not establish that a task finished or tests passed.\n\nKeep recurring scheduling in your AI client, CI system, or scheduler. Agree on refresh cadence, escalation, and notification behavior before enabling a workflow.\n\nFor exact options and current hook setup, use the [Swift CLI README](https://github.com/AndreasInk/agent-alerts-cli). For a service running outside macOS, use the [webhook API](/agent-alerts/docs/webhook-api).\n","path":"docs/swift-cli","url":"https://www.andreas.ink/agent-alerts/docs/swift-cli","markdownUrl":"https://www.andreas.ink/api/agent-alerts/content?path=docs%2Fswift-cli&format=markdown"},{"id":"agent-alerts-doc-webhook-api","kind":"doc","slug":"webhook-api","title":"Webhook API","description":"Send HTTPS updates from services, scripts, and unattended workflows.","keywords":["Agent Alerts","API","webhook","HTTP","token","JSON","idempotency"],"updatedAt":"2026-11-12","content":"# Webhook API\n\nSend HTTPS updates from services, scripts, and unattended workflows.\n\nSend an HTTPS request from a script, service, or unattended workflow. Your workflow handles the work and scheduling; Agent Alerts handles the phone update.\n\n## Create a publishing connection\n\nOpen [computer setup](/agent), choose publish-only access, then scan and approve the request in Agent Alerts on iPhone. Compare the code shown on both devices.\n\nThe website reveals the publishing token once after approval. Save it directly in your workflow's secret store as `AGENTALERTS_AGENT_TOKEN`. Keep it out of source code, URLs, logs, and chat.\n\n## Send an update\n\nMethod: `POST`\n\nEndpoint:\n\n```text\nhttps://www.andreas.ink/api/agent\n```\n\nConfigure these headers through your automation tool's secret-variable picker:\n\n```text\nAuthorization: Bearer <token from your secret store>\nContent-Type: application/json\nIdempotency-Key: first-test-001\n```\n\nSend this JSON body:\n\n```json\n{\n  \"title\": \"Webhook test\",\n  \"summary\": \"Hello from my workflow.\",\n  \"status\": \"good\",\n  \"activity_id\": \"my-workflow\",\n  \"source_name\": \"My workflow\",\n  \"surfaces\": [\"live_activity\", \"notification\"],\n  \"idempotency_key\": \"first-test-001\"\n}\n```\n\nUse non-sensitive content for the first test and confirm the result on your iPhone. Lock Screen content can be visible to people near the device.\n\n## IDs and retries\n\nKeep `activity_id` stable for updates about the same subject. Assign each new event a new `idempotency_key`, matching the header and body. Reuse a key only to retry that exact event with the same payload.\n\nA stable activity ID identifies the surface to update. An idempotency key identifies one send event. They serve different purposes.\n\n## Interpret the response\n\n- HTTP `401` means authentication failed. Do not report success from a success-looking body after a failed HTTP status.\n- `no_targets` means the account has no registered target for the requested surface.\n- `quota_limited` means the original alert was suppressed by the account's delivered-alert limit. Check `original_alert_delivered` and `retryable`; do not retry a non-retryable quota result or call it delivered.\n- An accepted request or APNs acceptance does not establish visible iPhone delivery. Confirm the phone result during setup.\n\nFree accounts have 350 delivered-alert events per UTC day. Pro accounts, including lifetime Pro, have 3,500. A send to multiple alert surfaces counts once; widget-only refreshes do not consume that delivered-alert allowance. See [pricing](/agent-alerts/pricing) for the published plans.\n\n## Responses and credentials\n\nPublish-only credentials send updates. Interactive responses require Pro and appropriate access on the originating connection. See [responses and permissions](/agent-alerts/docs/responses-and-permissions) before building an approval workflow.\n","path":"docs/webhook-api","url":"https://www.andreas.ink/agent-alerts/docs/webhook-api","markdownUrl":"https://www.andreas.ink/api/agent-alerts/content?path=docs%2Fwebhook-api&format=markdown"},{"id":"agent-alerts-doc-live-activity-examples","kind":"doc","slug":"live-activity-examples","title":"Live Activity examples","description":"See all ten Live Activity types, with native previews and guidance for choosing the right one.","keywords":["Agent Alerts","examples","health","incident","trend","comparison","progress","checklist","approval","funnel","launch","document","Live Activity"],"updatedAt":"2026-11-11","content":"# Live Activity examples\n\nSee all ten Live Activity types, with native previews and guidance for choosing the right one.\n\nChoose a presentation that fits the evidence you have, then update one activity as the result changes.\n\nAll ten content kinds from the MCP catalog are shown below. These are native iOS previews with illustrative sample data, not live measurements or proof of delivery to a phone.\n\nChoose a type: [Health](#system-health), [Incident](#active-incident), [Trend](#measured-trend), [Comparison](#category-comparison), [Approval](#approval), [Funnel](#activation-funnel), [Progress](#task-progress), [Checklist](#release-checklist), [Launch](#launch-console), or [Document](#living-brief).\n\nEach type includes an MCP sample request and a CLI content download. MCP requests use semantic content and may show different sample values from the image. CLI downloads reproduce the native preview content, with timestamps and routing managed by the CLI. The Approval CLI file is a visual preview only; use an interaction-capable MCP request for a real decision. Follow [CLI setup](/agent-alerts/docs/swift-cli), then send a downloaded content file with `agentalerts send --file health-cli.json --activity-id health`. Replace every sample fact with your own observed evidence before sending. CLI sends also include a notification.\n\n## System health\n\nUse `health` for a calm view of the systems you actually checked. This preview shows Ops Status OK with no open incidents. Name the checked scope and leave unavailable systems unknown.\n\n![Green health Live Activity showing Ops Status OK, 0 open incidents, and normal revenue, payments, and API checks.](/agent-alerts/content/live-activities/health.png)\n\n[Download the health MCP sample request](/agent-alerts/content/live-activities/health-mcp.json).\n\n[Download the health CLI content](/agent-alerts/content/live-activities/health-cli.json).\n\n## Active incident\n\nUse `incident` when an observed fault needs attention and a concrete next action. This preview shows a 4.2% error rate and timeout bursts, with a prompt to inspect the affected revision.\n\n![Pink incident Live Activity showing a 4.2% error rate, timeout bursts, and a next step to inspect logs and divert traffic.](/agent-alerts/content/live-activities/incident.png)\n\n[Download the incident MCP sample request](/agent-alerts/content/live-activities/incident-mcp.json).\n\n[Download the incident CLI content](/agent-alerts/content/live-activities/incident-cli.json).\n\n## Measured trend\n\nUse `trend` for ordered measurements over time. This preview shows trial-to-paid conversion at 49%, down 3 points, with a line chart. Keep the measurement window and whether the series shows change or accumulation clear.\n\n![Purple trend Live Activity showing trial-to-paid conversion at 49%, down 3 points, above a line chart.](/agent-alerts/content/live-activities/trend.png)\n\n[Download the trend MCP sample request](/agent-alerts/content/live-activities/trend-mcp.json).\n\n[Download the trend CLI content](/agent-alerts/content/live-activities/trend-cli.json).\n\n## Category comparison\n\nUse `comparison` for discrete categories or periods measured on the same basis. This preview shows 1,284 downloads, up 21%, with seven daily bars. Pair real labels with the corresponding values.\n\n![Green comparison Live Activity showing 1,284 downloads, up 21%, with seven daily bars.](/agent-alerts/content/live-activities/comparison.png)\n\n[Download the comparison MCP sample request](/agent-alerts/content/live-activities/comparison-mcp.json).\n\n[Download the comparison CLI content](/agent-alerts/content/live-activities/comparison-cli.json).\n\n## Approval\n\nUse `approval` only for a real yes-or-no decision. This preview shows a release awaiting a human decision after its checks passed. Approval requires Pro and notification delivery; the image itself is not an interactive approval. Wait for a recorded response before acting. See [responses and permissions](/agent-alerts/docs/responses-and-permissions).\n\n![Orange approval Live Activity showing Ready, awaiting you, with instructions to approve or hold the release.](/agent-alerts/content/live-activities/approval.png)\n\n[Download the approval MCP sample request](/agent-alerts/content/live-activities/approval-mcp.json).\n\n[Download the approval CLI visual preview](/agent-alerts/content/live-activities/approval-cli.json). This reproduces the displayed card only. It does not create a question, response controls, or durable approval; use the MCP request and [Interactions](/agent-alerts/docs/interactions) for that.\n\n## Activation funnel\n\nUse a funnel when you have measured stages for the same cohort and time window. The sample shows Opened 100%, Setup 72%, Ready 58%, and First Walk 41%.\n\n![Blue funnel Live Activity showing Opened 100%, Setup 72%, Ready 58%, and First Walk 41%.](/agent-alerts/content/live-activities/funnel.png)\n\n[Download the funnel MCP sample request](/agent-alerts/content/live-activities/funnel-mcp.json).\n\n[Download the funnel CLI content](/agent-alerts/content/live-activities/funnel-cli.json), then send it after [CLI setup](/agent-alerts/docs/swift-cli):\n\n```bash\nagentalerts send --file funnel-cli.json --activity-id funnel\n```\n\nUpdate the stage values as that cohort moves through onboarding. Missing measurements are unknown, not zero.\n\n## Task progress\n\nUse progress when completed and total work are known. The gallery example is 18 of 25 steps, or 72%, with visual verification as the next milestone.\n\n![Orange progress Live Activity showing a 72% ring, 18 of 25 completed steps, and visual verification as the next milestone.](/agent-alerts/content/live-activities/progress.png)\n\n[Download the progress MCP sample request](/agent-alerts/content/live-activities/progress-mcp.json).\n\n[Download the progress CLI content](/agent-alerts/content/live-activities/progress-cli.json). Keep the denominator grounded in the actual task; do not invent a completion percentage for open-ended work.\n\n## Release checklist\n\nUse a checklist when named steps matter more than a smooth percentage. Show what passed, what remains, and the next step.\n\n![Orange checklist Live Activity showing 7 of 10 steps with seven filled segments and three remaining release checks.](/agent-alerts/content/live-activities/checklist.png)\n\n[Download the checklist MCP sample request](/agent-alerts/content/live-activities/checklist-mcp.json).\n\n[Download the checklist CLI content](/agent-alerts/content/live-activities/checklist-cli.json).\n\n## Launch console\n\nUse a launch console for a compact summary with the facts and next action needed to review a release. State what was checked and leave uncertain outcomes uncertain.\n\n![Gold launch Live Activity showing MRR of $18.2k, down 8%, trial conversion of 14.6%, up 2.1%, and a revenue trend.](/agent-alerts/content/live-activities/launch.png)\n\n[Download the launch MCP sample request](/agent-alerts/content/live-activities/launch-mcp.json).\n\n[Download the launch CLI content](/agent-alerts/content/live-activities/launch-cli.json).\n\n## Living brief\n\nUse a document-style activity for a short brief that becomes more useful as the work progresses. Keep the summary concise and link to the full authorized destination when the reader needs more context.\n\n![Blue document Live Activity showing Launch ready at 86% beside release notes for onboarding, alerts, widgets, and device smoke.](/agent-alerts/content/live-activities/document.png)\n\n[Download the document MCP sample request](/agent-alerts/content/live-activities/document-mcp.json).\n\n[Download the document CLI content](/agent-alerts/content/live-activities/document-cli.json).\n\n## Keep updates useful\n\nReuse the same activity ID for the same subject. Send meaningful changes, not every internal step. Ask which blockers should notify the user and which can wait in the activity.\n\nFor sensitive figures, use neutral Lock Screen copy and keep the detail in an authenticated destination. Agent Alerts does not automatically redact what your workflow sends.\n","path":"docs/live-activity-examples","url":"https://www.andreas.ink/agent-alerts/docs/live-activity-examples","markdownUrl":"https://www.andreas.ink/api/agent-alerts/content?path=docs%2Flive-activity-examples&format=markdown"},{"id":"agent-alerts-doc-builder-layouts","kind":"doc","slug":"builder-layouts","title":"Builder layouts","description":"Build custom Live Activity layouts with constrained JSON nodes and bound data.","keywords":["Agent Alerts","builder","layouts","customize","builderSpec","data","Dynamic Island","JSON"],"updatedAt":"2026-11-11","content":"# Builder layouts\n\nBuild custom Live Activity layouts with constrained JSON nodes and bound data.\n\nCustomize a Live Activity with a small JSON layout: choose the visible fields, arrange them, and bind them to values from your task.\n\n## Start with a preset or a custom layout\n\nFor most updates, `agentalerts_publish_live_activity` chooses a layout from the semantic content kind. Browse [Live Activity examples](/agent-alerts/docs/live-activity-examples) first.\n\nUse the advanced `agentalerts_send` tool when you need direct layout control. It supports builder presets such as `builder-funnel`, `builder-launch-console`, and `builder-document-preview`, or a custom `builderSpec` with `data`.\n\nA supplied `presentationPreset` takes precedence over conflicting presentation fields. For an intentional custom builder layout, omit the preset and set `payload.template` to `builder`.\n\n## Layout structure\n\nA builder spec has `version: 1` and a `surfaces` object. Supply `lockScreen` as the required fallback. You can also define `compact`, `minimal`, and `expanded` for Dynamic Island presentations.\n\nEach surface contains a node. Supported node types are:\n\n- Layout: `vstack`, `hstack`, `zstack`, `grid`.\n- Content: `text`, `metric`, `chart`, `progress`, `documentPreview`.\n- Supporting elements: `statusDot`, `imageSymbol`, `button`, `spacer`, `divider`.\n\nStacks and grids contain `children`. Text and button nodes need `text`; metrics need `value`; charts need `values`; progress nodes need `progress`; image symbols need `symbol`. Document previews need `text` and `value`.\n\nVisible values can be literals or bindings such as `{\"path\":\"checks\"}`, resolved from `payload.data`. Use `fallback` where appropriate for a missing binding. Keep unavailable measurements distinct from zero.\n\n## Minimal custom MCP example\n\nThis illustrative request displays a release check count. Replace the sample facts with your observed result before sending:\n\n```json\n{\n  \"activityId\": \"release-summary\",\n  \"updateMode\": \"upsert_single\",\n  \"surfaces\": [\"live_activity\"],\n  \"payload\": {\n    \"template\": \"builder\",\n    \"title\": \"Release checks\",\n    \"summary\": \"Five checks passed.\",\n    \"status\": \"good\",\n    \"sourceName\": \"Release workflow\",\n    \"builderSpec\": {\n      \"version\": 1,\n      \"surfaces\": {\n        \"lockScreen\": {\n          \"type\": \"vstack\",\n          \"spacing\": \"small\",\n          \"children\": [\n            {\"type\": \"text\", \"text\": \"Release checks\", \"role\": \"title\"},\n            {\"type\": \"metric\", \"label\": \"Passed\", \"value\": {\"path\": \"checks\"}}\n          ]\n        },\n        \"compact\": {\"type\": \"text\", \"text\": {\"path\": \"checks\"}, \"role\": \"value\"},\n        \"minimal\": {\"type\": \"statusDot\"}\n      }\n    },\n    \"data\": {\"checks\": \"5\"}\n  }\n}\n```\n\nReuse the same `activityId` with `upsert_single` to update the same subject. Omit an explicit `event` so the service can choose update-or-start routing. Inspect the send receipt and verify the result on your iPhone; acceptance by APNs is not proof of rendering.\n\n## Customize the presentation\n\n- **Spacing:** `none`, `small`, `medium`, or `large`.\n- **Roles:** `title`, `subtitle`, `caption`, `value`, `label`, `status`, `accent`, `muted`, `funnel`, or `hero`.\n- **Charts:** `line`, `area`, or `bar`; supply numeric `values` and optional `axisLabels`.\n- **Progress:** `linear`, `ring`, or `segmented`; provide a measured value in the supported 0–1 or 0–100 range.\n- **Symbols:** an SF Symbol name through `symbol`, not a remote image URL.\n- **Accent:** `accentHex`, such as `#2E61EB`, and `glassOpacity` between 0.25 and 1.\n- **Navigation:** set the report's `deepLink` to a verified destination. A builder button uses that destination; a node-level `url` is not a supported navigation field.\n\nDocument previews support up to four text children. The document-card data format can also carry up to four carousel cards, `currentCardIndex`, `documentTitle`, `stateLabel`, `stateValue`, `lineOne` through `lineFour`, `itemStyle`, and zero-based `checkedLines`. Carousel cycling and checkbox changes remain local to the Live Activity. They do not edit source documents or count as agent approval. Use [Interactions](/agent-alerts/docs/interactions) when the agent needs a durable response.\n\n## Use the right format for your client\n\nThe example above is a remote MCP request envelope. The [Swift CLI](/agent-alerts/docs/swift-cli) accepts content files containing `builderSpec` and `data`; gallery downloads are already prepared for that format. Do not assume a whole MCP request can be passed unchanged to `agentalerts send --file`.\n\nBuilder layouts render Live Activity surfaces. They do not replace the fixed layout of a Home Screen snapshot widget. See [Widgets](/agent-alerts/docs/widgets) for snapshot delivery.\n\n## Limits and troubleshooting\n\nBuilder layouts use a constrained renderer, not arbitrary SwiftUI, HTML, CSS, or JavaScript. They cannot run scripts, fetch remote images, or perform network requests from the layout.\n\nCurrent validation limits include nesting depth five, up to eight children per ordinary container, up to four document-preview lines, up to 16 builder chart values, and up to 96 characters for builder text values. Symbol names are limited to 64 characters. Top-level report fields have their own limits, including 32 characters for `title` and 96 for `summary`. Keep the entire request compact enough for push delivery; a structurally valid layout is not a guarantee of successful transport or a readable design.\n\n- **Rejected layout:** check `version`, the required `lockScreen`, node types, required node fields, nesting, and field budgets. Use the returned field path to find the issue.\n- **Blank or missing value:** confirm the path exists in `data` and resolves to the expected type. Use a truthful fallback for missing data.\n- **Unexpected preset layout:** remove `presentationPreset` if you intend to use your own spec.\n- **Button opens the wrong place:** set `payload.deepLink`; do not put a URL on the button node.\n- **Crowded content:** shorten the copy and simplify compact/minimal layouts. Do not rely on truncation to preserve meaning.\n- **Layout accepted but not visible:** inspect delivery status and device registration, then check the phone. A schema-valid request is not an on-device rendering test.\n","path":"docs/builder-layouts","url":"https://www.andreas.ink/agent-alerts/docs/builder-layouts","markdownUrl":"https://www.andreas.ink/api/agent-alerts/content?path=docs%2Fbuilder-layouts&format=markdown"},{"id":"agent-alerts-doc-widgets","kind":"doc","slug":"widgets","title":"Widgets","description":"Place Home Screen and Lock Screen snapshot widgets, publish updates, and understand refresh behavior.","keywords":["Agent Alerts","widgets","Home Screen","Lock Screen","snapshot","WidgetKit"],"updatedAt":"2026-11-11","content":"# Widgets\n\nPlace Home Screen and Lock Screen snapshot widgets, publish updates, and understand refresh behavior.\n\nKeep a recent report on your Home Screen or Lock Screen, and use Live Activities for richer dashboard layouts.\n\n## Choose the right kind of widget\n\nSnapshot widgets show the latest received widget report. Add them through the iPhone's widget gallery. Home Screen sizes are small and medium; Lock Screen options are inline, circular, and rectangular.\n\nA Live Activity appears on the Lock Screen and, on supported iPhones, Dynamic Island. Its lifecycle and layout are separate from a placed snapshot widget. Use [Builder layouts](/agent-alerts/docs/builder-layouts) to customize a Live Activity through JSON.\n\n## Add a snapshot widget\n\n1. Install Agent Alerts, finish onboarding, and sign in to the account connected to your publishing client. Open the app and let device registration finish.\n2. To add a Home Screen widget, touch and hold the Home Screen, open its widget picker, search for Agent Alerts, and choose small or medium.\n3. For a Lock Screen widget, customize the Lock Screen and choose Agent Alerts from the widget picker. Choose a size that fits the available space.\n4. Send a widget update from a connected client, then check the placed widget on the iPhone.\n\nThe current snapshot widget shows the latest received report. It does not offer a per-instance report picker. Sending different widget IDs does not make each placed copy display an independently selected report.\n\n## Publish a widget snapshot\n\nUse the advanced remote MCP tool, `agentalerts_send`, for widget delivery. Add `widget` to `surfaces` and include a matching `widget` object with `widgetId` and `snapshot`. The snapshot uses the report content fields, such as `title`, `summary`, `status`, and metric fields.\n\nThis illustrative widget-only request does not start a Live Activity or request a visible notification:\n\n```json\n{\n  \"activityId\": \"release-summary\",\n  \"surfaces\": [\"widget\"],\n  \"payload\": {\n    \"title\": \"Release checks\",\n    \"summary\": \"Five checks passed.\",\n    \"status\": \"good\"\n  },\n  \"widget\": {\n    \"widgetId\": \"release-summary\",\n    \"snapshot\": {\n      \"title\": \"Release checks\",\n      \"summary\": \"Five checks passed.\",\n      \"status\": \"good\",\n      \"sourceName\": \"Release workflow\",\n      \"primaryLabel\": \"Checks passed\",\n      \"primaryValue\": \"5\"\n    }\n  }\n}\n```\n\nReplace sample values with observed results. Use small, non-secret content because widgets can be visible while the phone is locked. The publishing connection needs the appropriate sending access; `agentalerts_status` reports linked-account readiness and limits.\n\nThe normal `agentalerts_publish_live_activity` tool is for Live Activities. Use the advanced send tool when you explicitly need a widget surface. A widget refresh does not create a recurring data collection schedule.\n\n## Refresh and troubleshooting\n\nThe app stores an incoming snapshot and asks WidgetKit to reload. iOS controls refresh timing and can combine or delay reload requests. A successful service send is not proof that a placed widget has repainted.\n\n- **No widget appears:** add it through the iPhone's widget picker.\n- **Old or sample content:** open Agent Alerts, check the connected account and device registration, and send a fresh widget snapshot. The widget shows preview content until a snapshot is available.\n- **Wrong report:** the placed widget uses the latest received snapshot, including reports sent with another widget ID.\n- **Missing update:** check `status`, `failureCode`, `nextAction`, and target counts in the send response. Confirm that `surfaces` includes `widget` and its object contains both `widgetId` and `snapshot`.\n- **Different layout than expected:** snapshot widgets have fixed size-specific layouts. A custom `builderSpec` controls Live Activity layouts, not the placed Home Screen widget's view hierarchy.\n\nSee [Troubleshooting](/agent-alerts/docs/troubleshooting) for connection and delivery checks.\n","path":"docs/widgets","url":"https://www.andreas.ink/agent-alerts/docs/widgets","markdownUrl":"https://www.andreas.ink/api/agent-alerts/content?path=docs%2Fwidgets&format=markdown"},{"id":"agent-alerts-doc-notifications","kind":"doc","slug":"notifications","title":"Notifications","description":"Send an iPhone notification on its own or with a Live Activity, customize it, and check delivery and response status.","keywords":["Agent Alerts","notifications","push","iPhone","MCP","interactions","permissions","attention"],"updatedAt":"2026-11-12","content":"# Notifications\n\nSend an iPhone notification on its own or with a Live Activity, customize it, and check delivery and response status.\n\nSend a notification when an update needs attention on your iPhone. Use a quiet Live Activity for routine progress, and reserve notifications for the findings, blockers, or finished results you agreed to receive.\n\n## Before you start\n\nInstall Agent Alerts, sign in, and allow notifications when prompted. If permission was declined, review Agent Alerts in iPhone Settings and enable the notification options you want. Open the app to refresh its device registration, then connect your agent using [remote MCP](/agent-alerts/docs/remote-mcp).\n\nThe app's notification permission and its Live Activity and alarm permissions are separate. Notification appearance and sound also depend on iOS settings, including Focus and notification delivery settings.\n\n## Send a notification on its own\n\nFor example:\n\n```text\nSend one Agent Alerts notification to my iPhone titled “Setup check” with the message “Your notification connection is ready to test.” Do not start a Live Activity. Tell me the returned delivery status, and I will confirm it on my phone.\n```\n\nThe native MCP tool for explicit surface routing is `agentalerts_send`. Set `surfaces` to `[\"notification\"]` and include the required notification object. The tool also requires an activity ID and payload even for a notification-only request:\n\n```json\n{\n  \"activityId\": \"notification-setup-check\",\n  \"surfaces\": [\"notification\"],\n  \"payload\": {\n    \"title\": \"Setup check\",\n    \"summary\": \"Your notification connection is ready to test.\"\n  },\n  \"notification\": {\n    \"title\": \"Setup check\",\n    \"body\": \"Your notification connection is ready to test.\",\n    \"threadId\": \"setup-checks\"\n  }\n}\n```\n\nThis is an MCP argument example. Webhook and CLI request shapes differ. A notification-only send does not require a Live Activity presentation preset.\n\n## Notify alongside a Live Activity\n\nFor normal Live Activity work, use `agentalerts_publish_live_activity` with one stable `activityKey` for the subject. Its `importance` setting controls attention:\n\n- `persistent` keeps non-approval Live Activity updates quiet. Approval content always includes notification delivery and an interaction.\n- `attention` adds a visible notification.\n- `response_required` is for an approval question and requires Pro.\n\nFor explicit multi-surface sends, use `agentalerts_send` and include both `live_activity` and `notification` in `surfaces`, with the required content for each. See [keeping one Live Activity current](/agent-alerts/blog/keep-one-live-activity-current).\n\n## Customize the message\n\nThe notification object supports:\n\n- `title`, up to 80 characters, and `body`, up to 240 characters. Both are required.\n- `subtitle`, up to 80 characters.\n- `threadId`, up to 128 characters, to group related notifications in Notification Center.\n- `deepLink`, up to 500 characters, to open relevant context. Use a verified destination that the user can access.\n- `interruptionLevel`: `passive`, `active`, or `time-sensitive`.\n\nA grouping ID groups messages; it does not guarantee that an earlier notification will be replaced. Interruption level is a request to iOS, not a promise to bypass the user's settings. The tool does not offer a critical-alert level, arbitrary sound selection, or AlarmKit scheduling through this object.\n\n## Request a response\n\nInteractive alerts are a Pro feature. Yes/No and text responses require notification delivery and a real interaction request. Keep the returned `interactionId` and poll `agentalerts_interaction_status` through the originating connection.\n\nA delivered notification, tap, pending response, or expired question does not establish Yes/No approval. Act only on the explicit answer to the intended question. See [responses and permissions](/agent-alerts/docs/responses-and-permissions).\n\n## Delivery, limits, and troubleshooting\n\nA `sent` result or successful target count reports APNs acceptance, not proof that a banner appeared or someone read it. Inspect the requested surfaces, `deliveryStage`, failure details, and any `nextAction`. Confirm the first test on your iPhone.\n\nNotifications and Live Activities share the delivered-alert allowance. Free accounts have 350 delivered-alert events per UTC day. Pro accounts, including lifetime Pro, have 3,500. Sending both surfaces as one event counts as one delivered-alert event when accepted. Review [pricing](/agent-alerts/pricing) for the current plan.\n\n- **`no_targets`:** open Agent Alerts and check the account, notification permission, and device registration.\n- **`partial`:** some delivery attempts failed. Inspect the receipt before retrying.\n- **`quota_limited`:** the original update was not delivered. If `retryable` is false, do not keep resending it.\n- **Accepted, but not visible:** check iOS notification settings, Focus, and Notification Center. Keep the result described as accepted until confirmed on the device.\n\nFor recurring checks, use your agent's scheduler and agree on when a notification is worth sending. Connecting Agent Alerts does not start monitoring. For a timed alarm rather than an ordinary notification, see [alarms](/agent-alerts/docs/alarms).\n","path":"docs/notifications","url":"https://www.andreas.ink/agent-alerts/docs/notifications","markdownUrl":"https://www.andreas.ink/api/agent-alerts/content?path=docs%2Fnotifications&format=markdown"},{"id":"agent-alerts-doc-alarms","kind":"doc","slug":"alarms","title":"Alarms","description":"Set an explicitly requested one-shot alarm on your iPhone and understand permissions, timing, and delivery results.","keywords":["Agent Alerts","alarms","AlarmKit","iPhone","Pro","permissions","MCP","reminders"],"updatedAt":"2026-11-11","content":"# Alarms\n\nSet an explicitly requested one-shot alarm on your iPhone and understand permissions, timing, and delivery results.\n\nUse an alarm when you explicitly want an urgent reminder on your linked iPhone. Agent Alerts sends a push command, then the iPhone uses AlarmKit to schedule a one-shot alarm.\n\n## Before you start\n\n- Use an iPhone running iOS 26 or later and sign in to Agent Alerts.\n- In Agent Alerts Settings, choose **Enable Alarms** and approve the system permission. The app offers alarm setup as a Pro feature.\n- Keep notification permission and device registration working so the phone can receive the command.\n- Connect your AI client through [remote MCP](/agent-alerts/docs/remote-mcp). A publishing-token connection needs the `send_alarm` scope; ordinary publishing access alone does not grant alarm access.\n\nAsk your agent to check Agent Alerts status if the account or device connection is uncertain. A registered device is not proof that alarm permission is enabled.\n\n## Ask for one alarm\n\nFor example:\n\n```text\nSet one Agent Alerts alarm on my linked iPhone in 10 minutes titled “Take a break”. Tell me whether the push was accepted. I will check the alarm on my phone.\n```\n\nFor an exact clock time, include the date and time zone. The native MCP tool is `agentalerts_alarm`. This example shows its arguments, not webhook or CLI syntax:\n\n```json\n{\n  \"title\": \"Take a break\",\n  \"fireInSeconds\": 600,\n  \"alarmId\": \"break-reminder-001\"\n}\n```\n\nChoose exactly one schedule:\n\n- `fireInSeconds`: a positive whole number. The relative countdown starts when the phone processes the command, so network or background-processing delays can move the alarm later.\n- `fireAt`: an ISO 8601 date and time with a time-zone offset. Prefer this for a specific clock time.\n\nThe title can be up to 40 characters. An optional `alarmId` of up to 80 characters helps the phone suppress duplicate commands. Reuse it only for the same alarm; use a new ID for a different alarm. It is not an edit or cancellation handle.\n\nOptional `alertTitle` and `alertBody` customize the notification accompanying the command. `deepLink` opens supporting context when the alarm is tapped in Recent Alerts. `deviceInstallId` targets one known linked iPhone; project metadata only organizes the alert.\n\n## Alarm, notification, or Live Activity?\n\n- An **alarm** asks the phone to schedule an AlarmKit alarm. Use it only when the user requested an alarm.\n- A **notification** delivers a visible message through iOS notifications. It does not schedule an alarm.\n- A **Live Activity** keeps ongoing information visible on the Lock Screen or Dynamic Island. Scheduling a future Live Activity does not schedule an alarm.\n\nAn alarm command may also show a delivery notification. Even if its text says the alarm was scheduled, verify the phone's actual alarm state. The alarm tool does not create or update an Agent Alerts Live Activity.\n\n## Check the result\n\n- `sent`: APNs accepted the command for the reported targets.\n- `partial`: APNs accepted it for some targets, but others failed.\n- `no_targets`: no matching registered device was available.\n- `failed`: delivery failed for the attempted targets.\n\nThese are transport results. They do not confirm that the phone scheduled, displayed, or sounded the alarm. In Agent Alerts Settings, device diagnostics include the last alarm result and when it was handled.\n\n## Limits and troubleshooting\n\nThe current MCP catalog has no standalone alarm status or cancellation tool. Its scheduled Live Activity status and cancellation tools apply only to scheduled Live Activities. Recurring alarms are not part of this one-shot tool.\n\nIf you see **Alarm scope required**, use a connection approved for alarm access. If you get `no_targets`, open Agent Alerts, check the account and device registration, and confirm alarm and notification permissions before trying again.\n\nIf the push was accepted but no alarm appears, check the phone's last alarm diagnostic and system permission. Do not repeatedly send new IDs while the outcome is uncertain. A timestamp already in the past may be scheduled almost immediately when the phone handles it; choose future times with enough delivery margin.\n\nUse a directly configured device alarm for a time-critical reminder you cannot afford to miss. Remote delivery and background processing are not guaranteed. For ordinary updates, see [notifications](/agent-alerts/docs/notifications).\n","path":"docs/alarms","url":"https://www.andreas.ink/agent-alerts/docs/alarms","markdownUrl":"https://www.andreas.ink/api/agent-alerts/content?path=docs%2Falarms&format=markdown"},{"id":"agent-alerts-doc-interactions","kind":"doc","slug":"interactions","title":"Interactions","description":"Ask a question, read the matching response, and distinguish responses from delivery acknowledgments.","keywords":["Agent Alerts","interactions","responses","approvals","yes_no","text","polling","Pro"],"updatedAt":"2026-11-11","content":"# Interactions\n\nAsk a question, read the matching response, and distinguish responses from delivery acknowledgments.\n\nAsk for a tap, a Yes/No decision, or a short text reply, then read the response through the connected client.\n\n## What counts as an interaction\n\nInteractive alerts are available with Pro or Founder Pro. Supported kinds are:\n\n- `tap`: records an open or tap. It is not agreement to a separate action.\n- `yes_no`: asks a specific question with Yes and No responses.\n- `text`: asks for a text reply, up to 1,000 characters.\n\nYes/No and text requests require the notification surface, even when the same send also includes a Live Activity. Some Live Activity presentations provide response controls too, but their existence does not remove that delivery requirement. An interaction is a send-level request, not a Live Activity template.\n\n## Before sending\n\nCheck `agentalerts_status` if account readiness, Pro access, or permissions are unknown. A token-based interactive connection needs both `publish` and `interact`. An agent token can read only interactions it originated; an OAuth connection reads interactions owned by the linked account.\n\n`billing_reconciliation_pending` is not a final Pro denial. The interactive send can perform bounded server verification. Inspect the actual result rather than repeatedly resending a decision request.\n\nAsk one clear question and identify what the answer will authorize. Make sure notifications are allowed on the iPhone. Do not use an interaction to bypass your AI client's own confirmation or safety requirements.\n\n## Send a question through MCP\n\nFor a semantic approval Live Activity, use the approval content supported by `agentalerts_publish_live_activity`. Read `agentalerts_live_activity_examples` for the exact current request shape.\n\nFor a notification-only question, use `agentalerts_send`. This sample asks a low-stakes question and has no callback destination:\n\n```json\n{\n  \"activityId\": \"summary-format-question\",\n  \"surfaces\": [\"notification\"],\n  \"payload\": {\n    \"title\": \"Summary preference\",\n    \"summary\": \"Use a short bullet list?\",\n    \"status\": \"good\"\n  },\n  \"notification\": {\n    \"title\": \"Summary preference\",\n    \"body\": \"Would you like this summary as a short bullet list?\"\n  },\n  \"interaction\": {\n    \"kind\": \"yes_no\"\n  }\n}\n```\n\nKeep the returned `interactionId`. Expiry defaults to 24 hours. To choose a shorter deadline, supply a future ISO 8601 `expiresAt`; it cannot be more than seven days away.\n\nUse a fresh idempotency key for a new question. Reuse a key only to retry the exact same request, so an earlier answer cannot become permission for a different decision.\n\n## Read the answer\n\nCall `agentalerts_interaction_status` with the exact returned ID:\n\n```json\n{\n  \"interactionId\": \"REPLACE_WITH_RETURNED_INTERACTION_ID\"\n}\n```\n\n- `pending`: no accepted answer yet. It means neither Yes nor No.\n- `responded`: inspect `responseValue` and the matching interaction before proceeding.\n- `expired`: terminal. Do not interpret it as consent or continue polling.\n\nPoll with restraint and stop at a terminal state. The first accepted response wins; a duplicate submission returns the stored response. If the question changes materially, create a new interaction.\n\nThe current remote MCP exposes per-interaction status polling. It does not expose a general read-events feed or an event-acknowledgment tool. Do not substitute an assumed `read-events` or `ack` command for the documented polling flow.\n\n## Keep acknowledgments separate\n\nThese are different facts:\n\n- **Service acceptance:** APNs accepted an alert for delivery. It does not establish device visibility or a user response.\n- **Device acknowledgment:** the iPhone confirmed a particular operation. A Live Activity start acknowledgment is not an answer to a question.\n- **Interaction response:** the service stored the user's response to the matching interaction.\n- **Callback acknowledgment:** a callback receiver returned HTTP 2xx. It acknowledges receipt of that callback, not user approval or successful completion of the requested task.\n\nReading an interaction's status does not acknowledge a queue item or consume the answer.\n\n## Optional callbacks and local controls\n\nAn interaction can reference pre-registered callback destination IDs. Use only known, approved destinations. The receiver must verify the signed callback using the exact raw request body and deduplicate deliveries. Callback delivery is separate from the stored response, so inspect `callbackStatus` independently. See [Responses and permissions](/agent-alerts/docs/responses-and-permissions) for access boundaries.\n\nDocument cards can also offer local carousel and checkbox controls. Those controls change the Live Activity's local display. They do not automatically submit a durable interaction response, edit the source document, or authorize your agent to act.\n\n## Troubleshooting\n\n- **No interaction ID:** inspect the send result. An eligible delivery target is required to create an interaction. `not_created` is not a pending answer.\n- **Immediate expiry:** if every interaction-capable delivery fails, the service can expire the interaction rather than leave an unreachable question pending.\n- **No response actions:** verify the notification surface and matching notification object for `yes_no` or `text`, iPhone notification permissions, and current Pro/access readiness.\n- **Cannot read an ID:** use the exact returned ID and the originating token or correct linked account. Do not guess IDs or switch accounts to bypass access restrictions.\n- **Expired before answering:** ask again only if the decision is still needed, using a new interaction. Do not escalate to an alarm without the user's explicit request.\n\nThe Homebrew Swift CLI and remote MCP have different command sets. The Swift CLI implementation includes phone-approval hooks, but that does not establish a general `interaction status` or `interaction wait` command. Use the remote MCP flow above for direct polling and consult the current CLI README for hook support.\n","path":"docs/interactions","url":"https://www.andreas.ink/agent-alerts/docs/interactions","markdownUrl":"https://www.andreas.ink/api/agent-alerts/content?path=docs%2Finteractions&format=markdown"},{"id":"agent-alerts-doc-responses-and-permissions","kind":"doc","slug":"responses-and-permissions","title":"Responses and permissions","description":"Understand publishing access, Pro responses, explicit alarm requests, and revocation.","keywords":["Agent Alerts","permissions","Pro","responses","approval","interactions","security","privacy"],"updatedAt":"2026-11-10","content":"# Responses and permissions\n\nUnderstand publishing access, Pro responses, explicit alarm requests, and revocation.\n\nChoose the least access your workflow needs. Reading public docs, publishing an update, and asking for a response are separate capabilities.\n\n## Public knowledge access\n\nAnyone can read the published docs, pricing, and blog without an account. The public content MCP has read and search tools only. It cannot send alerts, read account activity, or approve actions.\n\n## Publishing access\n\nPublish-only connections can send updates for the connected account. Approve the connection on your iPhone and keep its token in your runtime's secret storage.\n\nUse account sign-in for the [remote MCP](/agent-alerts/docs/remote-mcp), or an iPhone-approved token for the [CLI](/agent-alerts/docs/swift-cli) and [webhook](/agent-alerts/docs/webhook-api). Review the access shown in the connection flow before approving it.\n\n## Interactive responses\n\nInteractive alerts are a Pro feature. They can request a tap, a Yes/No choice, or a text response. Yes/No and text interactions need a notification-capable send; they are not additional Live Activity templates.\n\nA token-based interactive connection requires both publishing and interaction access. It may read responses only for interactions it originated. Keep the returned interaction ID and poll the matching interaction's status through the supported client.\n\nOnly an explicit response to that interaction counts as the user's answer. Pending, expired, cancelled, mismatched, or failed responses do not grant permission. A successful send does not mean the user approved the requested action.\n\n## Alarms and scheduling\n\nAn alarm requires the user's explicit request and a connection with the required access. Do not turn an ordinary blocker, an unanswered question, or a quiet workflow into an alarm automatically.\n\nRecurring checks belong to your AI client or scheduler. Agree on what to check, how often to refresh, when to escalate, and where a tap should lead before scheduling the work.\n\n## Revoke access\n\nManage or revoke publisher access in the iPhone app. If a token is lost or exposed, revoke it and create a replacement. Token plaintext cannot be recovered.\n\nRevoking a publisher stops that credential from sending new updates. It does not promise deletion of content already visible on the iPhone. Review [privacy information](/agent-alerts/privacy) before sending sensitive material.\n","path":"docs/responses-and-permissions","url":"https://www.andreas.ink/agent-alerts/docs/responses-and-permissions","markdownUrl":"https://www.andreas.ink/api/agent-alerts/content?path=docs%2Fresponses-and-permissions&format=markdown"},{"id":"agent-alerts-doc-troubleshooting","kind":"doc","slug":"troubleshooting","title":"Troubleshooting","description":"Diagnose sign-in, authentication, missing targets, quotas, and visible delivery.","keywords":["Agent Alerts","help","error","401","no_targets","quota","delivery","support"],"updatedAt":"2026-11-12","content":"# Troubleshooting\n\nDiagnose sign-in, authentication, missing targets, quotas, and visible delivery.\n\nStart with one non-sensitive test and keep the client result separate from what is visible on your iPhone.\n\n## The connection cannot sign in\n\nUse the [remote MCP setup page](/agent/mcp) and the same account as your iPhone. Check that your AI client supports remote HTTP MCP and browser authentication. A connection to the public docs MCP only reads published content; it does not connect your account for sending alerts.\n\nFor an unattended runtime that cannot open a browser, use an iPhone-approved publishing token with the [webhook API](/agent-alerts/docs/webhook-api).\n\n## HTTP 401\n\nAuthentication failed. Check that the credential belongs to this runtime and has not been revoked. Supply it through the runtime's secret store, not a command argument or conversation.\n\nFor remote MCP, repeat the client's supported sign-in flow. For token-based publishing, create a replacement connection if the one-time token was lost. Do not log credentials while diagnosing the error.\n\n## No registered target\n\nA `no_targets` result means there is no registered target for the requested surface. Open Agent Alerts on your iPhone, confirm the account, finish onboarding, and review notification and Live Activity permissions. Try one update again after the phone has registered.\n\n## The request was accepted, but nothing appeared\n\nAPNs acceptance and visible delivery are different observations. Confirm the account and requested surface, check iPhone permissions, and inspect the returned delivery result. Keep the result described as accepted until you see it on the phone.\n\nDo not create a new activity ID on every retry. Keep a stable ID for the subject, and reuse an idempotency key only for the exact original event.\n\n## The account reached its limit\n\nCheck for `quota_limited`, `original_alert_delivered: false`, and `retryable: false`. The original update was not delivered. Do not repeatedly retry a non-retryable quota result.\n\nFree accounts have 350 delivered-alert events per UTC day. Pro accounts, including lifetime Pro, have 3,500. Review [pricing](/agent-alerts/pricing) in the website or the current plan in the iPhone app before changing your workflow.\n\n## A CLI example failed\n\nConfirm that the JSON file is in your terminal's current folder. Use the [Swift CLI installation instructions](/agent-alerts/docs/swift-cli) and the JSON download paired with that gallery example.\n\nCLI content uses `data`; native example state may use `builderData`. The website's downloadable CLI files already make that conversion. An MCP request is a different request shape.\n\n## An approval is still pending\n\nDo not treat waiting, expiry, or a delivery acknowledgement as approval. Poll the exact interaction using the originating connection and inspect the returned response. See [responses and permissions](/agent-alerts/docs/responses-and-permissions).\n\n## Still stuck?\n\n[Email Andreas](mailto:me@andreas.ink) with the client name, the action you tried, the HTTP status or non-sensitive error, and what appeared on your phone. Remove tokens, private payloads, and personal data from anything you share.\n","path":"docs/troubleshooting","url":"https://www.andreas.ink/agent-alerts/docs/troubleshooting","markdownUrl":"https://www.andreas.ink/api/agent-alerts/content?path=docs%2Ftroubleshooting&format=markdown"},{"id":"agent-alerts-blog-keep-one-live-activity-current","kind":"blog","slug":"keep-one-live-activity-current","title":"Keep one Live Activity current","description":"Use a stable activity ID to update one useful result as your work changes.","keywords":["Agent Alerts","workflow","stable activity ID","progress","Live Activity"],"publishedAt":"2026-11-10","updatedAt":"2026-11-10","content":"# Keep one Live Activity current\n\nUse a stable activity ID to update one useful result as your work changes.\n\nA background workflow can produce plenty of updates and still leave you with the same question: what needs me now?\n\nI built Agent Alerts to put a short, useful result on the iPhone. One of its most useful habits is simple: keep the same Live Activity current as the work changes.\n\n## Start with one subject\n\nChoose a subject you will want to glance at again: a release, a research task, or the same onboarding cohort. Give it a stable activity ID.\n\nThat ID is the thread connecting the updates. The next send should replace the useful state of that subject, rather than starting another surface with another name.\n\n## Report the evidence you have\n\nIf you know that 18 of 25 steps are finished, a progress ring is useful. If the work is open-ended, a short status and next step can be more honest than a percentage.\n\nFor a funnel, compare stages from the same cohort and time window. The [gallery's activation funnel](/agent-alerts#workflow) uses sample values of 100%, 72%, 58%, and 41%. Those are illustrative measurements, not customer results.\n\nAfter [installing the Swift CLI](/agent-alerts/docs/swift-cli), download [funnel.json](/agent-alerts/examples/funnel.json) and send the example:\n\n```bash\nagentalerts send --file funnel.json --activity-id funnel\n```\n\nWhen your real measurements change, update the content and reuse the same activity ID. Keep missing data unknown instead of turning it into zero.\n\n## Decide what deserves a notification\n\nA current Live Activity and an interruption do different jobs. Agree with your agent on what can sit quietly in the activity and what needs a notification.\n\nUseful triggers might be a result ready for review or a blocker that needs a decision. An internal step finishing is not automatically a reason to interrupt you. An agent turn ending also does not prove the whole task is finished.\n\nYour AI client still owns the checks, source access, and recurring schedule. Agent Alerts shows the result the workflow sends. Connecting it does not start monitoring by itself.\n\n## Check the first result\n\nUse a non-sensitive test, read the returned status, and look at your iPhone. A service accepting the request does not establish visible delivery.\n\nThe same care applies to the content. Keep sensitive details in an authenticated destination and use neutral Lock Screen copy when that is enough to help you decide what to open.\n\nThe aim is a useful glance: what changed, why it matters, and what to do next.\n\n[Send your first update](/agent-alerts/docs) or [explore the available examples](/agent-alerts/docs/live-activity-examples).\n","path":"blog/keep-one-live-activity-current","url":"https://www.andreas.ink/agent-alerts/blog/keep-one-live-activity-current","markdownUrl":"https://www.andreas.ink/api/agent-alerts/content?path=blog%2Fkeep-one-live-activity-current&format=markdown"},{"id":"agent-alerts-blog-chatgpt-codex-automations","kind":"blog","slug":"chatgpt-codex-automations","title":"How to use automations in ChatGPT and Codex","description":"Set up recurring tasks in ChatGPT and Codex, test permissions, and send useful results to Agent Alerts when your workflow supports it.","keywords":["Agent Alerts","ChatGPT automations","ChatGPT scheduled tasks","Codex automations","recurring AI tasks","Agent Alerts","MCP notifications"],"publishedAt":"2026-11-11","updatedAt":"2026-11-11","content":"# How to use automations in ChatGPT and Codex\n\nSet up recurring tasks in ChatGPT and Codex, test permissions, and send useful results to Agent Alerts when your workflow supports it.\n\nA useful automation answers a question you would otherwise keep checking: did the release finish, what changed in this project, or is there anything I need to review?\n\nStart with one question, a clear schedule, and a small result. Once that works, decide whether the result belongs in your chat, a notification, or an Agent Alerts Live Activity.\n\n## Choose where the work should run\n\nChatGPT scheduled tasks handle reminders, recurring updates, and monitoring. For longer work involving research, tools, and finished deliverables, ChatGPT Work provides the agent experience. Codex is the place for repository reviews, tests, and other software development work. [OpenAI’s guide to Work and Codex](https://help.openai.com/en/articles/20001275-chatgpt-work-and-codex) explains the current choices.\n\nThe schedule decides when to start. The selected environment decides which files, tools, and accounts the task can actually use.\n\nFor a Codex task using a local project, keep your computer on, the desktop app running, and the project available on disk. Don’t assume a local schedule moves to the cloud when your laptop sleeps. See [OpenAI’s automation documentation](https://developers.openai.com/codex/app/automations).\n\n## Set up a ChatGPT scheduled task\n\nOpen **Scheduled**, or ask ChatGPT to create a task. Give it the work, cadence, time zone, and expected output. Review the saved task before relying on it.\n\nTry a simple reminder first:\n\n> Every weekday at 9 AM America/New_York, remind me to review my release checklist. Keep the reminder to one sentence.\n\nYou can manage tasks from Scheduled and configure push or email notifications in **Settings → Notifications**. Availability, active-task limits, and supported schedules depend on your account and workspace. [ChatGPT scheduled tasks](https://help.openai.com/en/articles/10291617-scheduled-tasks-in-chatgpt)\n\nFor a connected workflow, name the source and keep the first version read-only:\n\n> Every Monday at 9 AM America/New_York, check open pull requests in [repository] using the connected GitHub app. Report reviews waiting on me and failing checks, with links. Do not edit files, post comments, or merge anything. If access fails, report the blocker.\n\nReplace the repository placeholder before scheduling.\n\nEligible Work accounts also support event-triggered tasks for selected app events. Review the trigger and conditions. Connecting an app alone does not create that task. Required approvals can pause a run. [Scheduled task triggers and permissions](https://help.openai.com/en/articles/10291617-scheduled-tasks-in-chatgpt)\n\n## Set up a Codex automation\n\nOpen the relevant project in Codex and test the prompt manually. Then ask Codex to schedule it. Specify whether future runs should continue the same chat or produce independent reports.\n\nFor example:\n\n> Every weekday at 9 AM America/New_York, review commits from the previous 24 hours in this project’s local Git history. Identify concrete regression risks with file references. Do not edit files, install dependencies, push commits, or contact anyone. If there are no actionable findings, say so briefly. Create a separate report for each run.\n\nWhen changes are part of an authorized workflow, a Git worktree can separate them from unfinished local work. Scheduled runs use sandbox and permission settings; restricted operations may fail. Start with narrow access rather than enabling full access to make a failing task run. [Codex scheduling and security](https://developers.openai.com/codex/app/automations)\n\nReview the first few runs. Check the source window, findings, and actual execution time before increasing the frequency.\n\n## Add Agent Alerts after the task works\n\nAgent Alerts displays the update your workflow sends. Your AI client or scheduler still owns the recurring work. Connecting Agent Alerts does not start monitoring.\n\nA send step is appropriate only when that run has a working Agent Alerts integration, the required tool, and permission to send the intended information. MCP availability can differ between clients, hosts, and plugins. A connection in one environment does not establish access everywhere. [OpenAI’s MCP documentation](https://developers.openai.com/codex/mcp)\n\nAfter testing the connection, you can add a scoped instruction:\n\n> When this check finds a blocker or completes the requested review, use the available Agent Alerts integration to update activity ID `release-review`. Send only a neutral status and next step. Keep private repository details out of Lock Screen text. If the send fails or requires approval, report that in this chat.\n\nFollow the [Agent Alerts setup guide](/agent-alerts/docs), send a non-sensitive test, and check your iPhone. An accepted request does not prove visible delivery.\n\n## Keep the automation worth running\n\nChoose a cadence that matches the decision. A daily project review rarely needs minute-by-minute checks. A temporary release watch should have an end condition.\n\nWrite down:\n\n- Which source the task may read.\n- What counts as a meaningful change.\n- What it may send or modify.\n- When it should stop or ask for help.\n\nKeep one stable activity ID for the same subject, and update it when there is something useful to show. [Keeping one Live Activity current](/agent-alerts/blog/keep-one-live-activity-current) explains that pattern.\n\nThe goal is a result you can trust, with enough context to know what to do next.\n\n## Choose a workflow for your role\n\nStart with a decision you already make. These guides show concrete checks, useful reporting windows, and the actions that still need your review:\n\n- [When Product Managers Should Use Automations](/agent-alerts/blog/when-product-managers-should-use-automations)\n- [When CEOs Should Use Automations](/agent-alerts/blog/when-ceos-should-use-automations)\n- [When Engineers Should Use Automations](/agent-alerts/blog/when-engineers-should-use-automations)\n- [When Marketers Should Use Automations](/agent-alerts/blog/when-marketers-should-use-automations)\n","path":"blog/chatgpt-codex-automations","url":"https://www.andreas.ink/agent-alerts/blog/chatgpt-codex-automations","markdownUrl":"https://www.andreas.ink/api/agent-alerts/content?path=blog%2Fchatgpt-codex-automations&format=markdown"},{"id":"agent-alerts-privacy","kind":"policy","slug":"privacy","title":"AgentAlerts Privacy Policy","description":"Information Agent Alerts collects, how it is used, and your privacy choices.","keywords":["Agent Alerts","Agent Alerts","privacy policy","data","account","retention","security"],"content":"# AgentAlerts Privacy Policy\n\nInformation Agent Alerts collects, how it is used, and your privacy choices.\n\n## Privacy Policy\n\nReportKit (\"AgentAlerts,\" \"we,\" \"us,\" or \"our\") provides an iPhone app, widget extension, command-line tool, and related hosted services that let you send operational updates, agent progress, alarms, and other report events to an iPhone Live Activity surface.\n\nThis Privacy Policy explains what information AgentAlerts collects, how we use it, and the choices you have. If you do not agree with this Privacy Policy, do not use ReportKit.\n\n## Information We Collect\n\n### Account information\n\nWhen you create or sign in to a AgentAlerts account, we collect information needed to authenticate you, such as your email address and authentication identifiers managed through Supabase Auth. We use this information to create your account, keep you signed in, and associate your iPhone app, CLI, widgets, agent tokens, Live Activity sends, and alarms with the correct user.\n\n### Device and notification information\n\nWhen you use the iPhone app, AgentAlerts may collect device-specific identifiers needed to deliver Live Activities and notifications, including:\n\n- ActivityKit push-to-start tokens\n- APNs device tokens\n- a AgentAlerts-generated device installation identifier\n- APNs environment information, such as sandbox or production\n- token sync timestamps and token upload status\n- notification, Live Activity, and alarm permission/status information shown in the app\n\nWe use this information to register your device, start or update Live Activities, send alarm notifications when requested, retry token uploads, and show token-sync status in the app.\n\n### Report, Live Activity, alarm, and widget content\n\nAgentAlerts processes the report content you or your workflows send through the CLI, hosted agents, or app, including fields such as titles, summaries, statuses, metrics, source names, icons, actions, deep links, builder specs, and other payload data you choose to provide.\n\nAgentAlerts does not decide what external business, analytics, infrastructure, or agent data you put into report payloads. You are responsible for avoiding sensitive personal information, secrets, credentials, private customer data, or regulated data in the payloads you send to AgentAlerts.\n\n### Agent token information\n\nIf you create AgentAlerts agent tokens for hosted agents or automation workflows, ReportKit stores the token name, token prefix, token hash, scopes, status, creation time, last-used time, and related metadata. Plaintext agent tokens are shown once when created and are not stored by AgentAlerts after creation.\n\n### Usage and delivery metadata\n\nAgentAlerts stores operational metadata needed to provide and debug the service, including Live Activity event records, idempotency keys, payload hashes, target counts, delivery counts, APNs response metadata, delivery status, daily Live Activity usage counts, entitlement/quota information, and timestamps.\n\n### Local CLI information\n\nThe AgentAlerts Swift CLI authenticates with a scoped Agent Alerts token supplied through an environment variable or a private local token file. Running `agentalerts setup` saves the approved pairing token to `~/.config/agent-alerts/token.env`, or the equivalent location under `XDG_CONFIG_HOME`. The file is owned by the current user and uses mode `0600` permissions so only that user can read or write it. The CLI parses the file as data, not as a shell script, and sends the token to AgentAlerts to authorize requests. It does not store a Supabase account session or back up credentials to macOS Keychain.\n\n## How We Use Information\n\nWe use the information we collect to:\n\n- authenticate users and keep sessions active\n- connect the CLI, iPhone app, widget extension, and hosted edge functions to the same account\n- register iPhone Live Activity and APNs tokens\n- send, update, or end Live Activities that you request\n- send alarm notifications that you request\n- manage agent tokens and authorize hosted automation sends\n- store and render widget configurations and builder templates\n- enforce plan limits, quotas, and abuse-prevention controls\n- record delivery outcomes and troubleshoot failed sends\n- maintain security, prevent unauthorized access, and protect the service\n- respond to support requests and improve product reliability\n\n## What We Do Not Do\n\nAgentAlerts is designed as a narrow operational delivery surface. We do not:\n\n- sell your personal information\n- use your report payloads for third-party advertising\n- require access to your Slack, email, analytics, App Store Connect, infrastructure, or other source systems\n- run a scheduler inside the CLI\n- store plaintext AgentAlerts agent tokens after creation\n- ask hosted agents to use your Supabase password or Supabase account session credentials\n\nAgentAlerts only receives the payloads and credentials you explicitly configure or send through the app, CLI, hosted edge functions, or your own automation.\n\n## How We Share Information\n\nWe share information only as needed to provide AgentAlerts, comply with law, protect rights and safety, or operate the service.\n\nAgentAlerts currently relies on service providers for functions such as authentication, database storage, edge functions, and push delivery. For example, Supabase is used for authentication, database records, and edge functions, and Apple services are used for APNs, notifications, Live Activities, and app platform functionality.\n\nWe may disclose information if required by law, legal process, or enforceable governmental request, or if we believe disclosure is necessary to protect the rights, property, or safety of AgentAlerts, our users, or others.\n\n## Data Storage and Security\n\nWe use technical and organizational safeguards intended to protect ReportKit data, including account-scoped authorization, row-level access controls where applicable, private local CLI token-file permissions, hashed agent-token storage, and avoiding privileged secrets in the public source repository.\n\nNo method of transmission or storage is completely secure. You should protect your account credentials, local CLI token files and token environment variables, cloud-agent secrets, and generated ReportKit agent tokens. Revoke any agent token that may have appeared in logs, prompts, commits, screenshots, or untrusted transcripts.\n\n## Data Retention\n\nWe retain account, token, widget, event, delivery, usage, and entitlement records for as long as needed to provide ReportKit, support operational debugging, comply with legal obligations, resolve disputes, and enforce agreements.\n\nSome records are deleted automatically when the related account is deleted because they are associated with the account user identifier. Other operational records may be retained as needed for security, auditability, reliability, or legal compliance.\n\n## Your Choices\n\nDepending on your account status and applicable law, you may have choices or rights to:\n\n- access, correct, or delete certain account information\n- sign out of the iPhone app\n- revoke ReportKit agent tokens\n- remove ReportKit from hosted agent environments\n- disable notifications or Live Activities through iOS settings\n- remove the local CLI token file and unset CLI token environment variables; revoke the token to disable any remaining copies\n- request account deletion or other privacy assistance by contacting us\n\nTo make a privacy request, use the contact details below.\n\n## Children\n\nReportKit is not intended for children under 13, and we do not knowingly collect personal information from children under 13. If you believe a child has provided personal information to ReportKit, contact us so we can take appropriate action.\n\n## International Users\n\nReportKit may process information in the United States or other countries where we or our service providers operate. These locations may have privacy laws different from those in your jurisdiction.\n\n## Changes to This Policy\n\nWe may update this Privacy Policy from time to time. If we make material changes, we will update the effective date and provide notice as required by law. Your continued use of ReportKit after an updated policy becomes effective means you accept the updated policy.\n\n## Contact\n\nFor privacy questions or requests, contact:\n\nAndreas Ink\n\nme@andreas.ink\n","path":"privacy","url":"https://www.andreas.ink/agent-alerts/privacy","markdownUrl":"https://www.andreas.ink/api/agent-alerts/content?path=privacy&format=markdown"},{"id":"agent-alerts-blog-when-product-managers-should-use-automations","kind":"blog","slug":"when-product-managers-should-use-automations","title":"When Product Managers Should Use Automations","description":"Use automations to review release readiness, dependencies, feedback, and scope while keeping product decisions with people.","keywords":["Agent Alerts","product manager automations","release readiness","feedback synthesis"],"publishedAt":"2026-11-11","updatedAt":"2026-11-11","content":"# When Product Managers Should Use Automations\n\nUse automations to review release readiness, dependencies, feedback, and scope while keeping product decisions with people.\n\nProduct managers often check the same sources before making a decision: the release checklist, a dependency board, a feedback collection, and the last agreed scope. An automation is useful when those checks have a repeatable question and a clear destination for the answer.\n\nStart with a decision you already make. “What changed that could affect Friday’s release?” is a better brief than “Monitor the product.” The first defines a window, relevant evidence, and a reason to interrupt you.\n\n## Four checks worth automating\n\n**Release readiness.** Trigger: a weekday check during the final week of a release. Authorized data: the named release checklist, linked issues, and available test results. Output: newly blocked criteria, missing evidence, and the decision each blocker requires. A green issue status is not proof that a release criterion passed. Ask the automation to link the actual evidence and mark unavailable results as unknown. Keep the launch decision with the responsible people.\n\n**Dependency changes.** Trigger: a morning review while a cross-team dependency is active. Authorized data: the specific dependency board and agreed milestone document. Output: changes to owners, dates, or acceptance criteria since the previous successful check. Have it draft a question for your review when a date changes without an explanation. Do not let it silently move downstream dates or promise a revised delivery window.\n\n**Feedback synthesis.** Trigger: a weekly review. Authorized data: a named, approved feedback collection with an explicit date range. Output: recurring problems, supporting references, and contradictions worth investigating. Count distinct contributors where the data supports that, rather than treating ten comments from one person as ten customers. Describe the collection’s limits. A support queue cannot establish prevalence across the entire customer base.\n\n**Scope drift.** Trigger: a review before the weekly planning meeting. Authorized data: the approved scope document and current project issues. Output: newly added work, removed requirements, and acceptance criteria that no longer match. Separate explicit changes from possible mismatches. The useful result is a short set of decisions for planning, not an automatically rewritten roadmap.\n\n## A prompt for the release window\n\nReplace the bracketed sources and choose a supported schedule in your environment:\n\n> Every weekday at 9 AM Europe/London until [release review date], compare [release checklist] and [dependency board] with the previous successful review. Read only these approved sources and their explicitly listed evidence links. Report at most three material changes that could affect release readiness. For each, include the source, what changed, missing evidence, and a question I need to resolve. Do not change issues, dates, priorities, or send messages to teammates. If a source is unavailable, name the gap instead of treating it as no change. Stop after the review date unless I extend the task.\n\nTest the prompt manually before scheduling it. The [ChatGPT and Codex automation guide](/agent-alerts/blog/chatgpt-codex-automations) explains how the runtime, source access, and schedule fit together.\n\n## Protect the decision and the context\n\nDo not automate prioritization from raw mention counts, infer customer intent from isolated quotes, or announce release dates without approval. Keep customer identifiers and confidential roadmap details inside approved destinations. A summary needs the same audience check as its source material.\n\nRun daily during a release window and weekly for broader feedback. Pause when the release ends, the source stops being maintained, or several reviews produce no decision worth making. Review false alarms before adding more sources.\n\nAgent Alerts can be an optional reporting surface if that runtime has the integration, send tool, and permission. A neutral notification such as “Release review needs a decision” can point you back to the detailed result. Follow the [notification guidance](/agent-alerts/docs/notifications), and verify delivery before depending on it. Agent Alerts displays the update; the scheduled workflow does the checking.\n","path":"blog/when-product-managers-should-use-automations","url":"https://www.andreas.ink/agent-alerts/blog/when-product-managers-should-use-automations","markdownUrl":"https://www.andreas.ink/api/agent-alerts/content?path=blog%2Fwhen-product-managers-should-use-automations&format=markdown"},{"id":"agent-alerts-blog-when-ceos-should-use-automations","kind":"blog","slug":"when-ceos-should-use-automations","title":"When CEOs Should Use Automations","description":"Prepare operating exception reports, runway reviews, and strategic decisions using validated numbers and explicit approval boundaries.","keywords":["Agent Alerts","CEO automations","business review","executive exception reporting"],"publishedAt":"2026-11-11","updatedAt":"2026-11-11","content":"# When CEOs Should Use Automations\n\nPrepare operating exception reports, runway reviews, and strategic decisions using validated numbers and explicit approval boundaries.\n\nA CEO usually needs fewer updates with clearer consequences. An automation earns its place when it identifies a verified exception, explains what changed, and brings forward a decision that cannot wait for the next business review.\n\nBegin with one agreed metric or commitment. Establish its definition, source, reporting delay, and responsible owner before scheduling a check. A fast summary of inconsistent numbers creates another problem to investigate.\n\n## Four executive checks with clear boundaries\n\n**Operating exceptions.** Trigger: a weekday review of a named operating dashboard. Authorized data: approved aggregate metrics with established definitions. Output: changes beyond thresholds you choose, compared with an appropriate baseline. Require the reporting period, freshness, and denominator. A conversion change during an incomplete day should not be presented as a completed-day result. Missing data belongs in a separate data-quality warning.\n\n**Runway review preparation.** Trigger: after the monthly finance package is available, using a supported event trigger or a scheduled check. Authorized data: the specifically approved finance summary and documented runway assumptions. Output: changes in the reported runway estimate, the assumptions behind them, and questions for the finance owner. Reconcile periods, units, and whether cash figures are actuals or forecasts. Do not extrapolate from partial transaction data or present an estimate as a validated cash position.\n\n**Strategic commitments.** Trigger: a weekly review before the leadership meeting. Authorized data: the agreed company priorities and leadership action log. Output: decisions awaiting you, material milestone changes, and conflicts between documented commitments. Ask for links and the last confirmed status. The automation can prepare a decision list; changing priorities, owners, or external commitments stays with the appropriate people.\n\n**Business review consistency.** Trigger: a scheduled check before the monthly review. Authorized data: the approved review deck and its named aggregate source reports. Output: mismatched reporting periods, changed metric definitions, and figures that disagree across documents. It should flag the discrepancy rather than choose whichever number looks plausible. This is especially useful when several teams contribute to one presentation.\n\n## A prompt for exception reporting\n\nPick thresholds with the metric owner and replace every placeholder:\n\n> Every weekday at 8 AM America/Los_Angeles through [review date], read [approved aggregate dashboard] and [metric definition document]. Check [metrics] against [explicit thresholds and baselines]. Use completed reporting periods only. Report a maximum of three material exceptions, each with its source, period, freshness, comparison, and the decision or validation needed. Separate stale, incomplete, and conflicting data from business exceptions. Do not invent missing numbers, revise forecasts, contact anyone, change records, or make purchases or transfers. If nothing qualifies, return a short no-exception result with the source timestamp.\n\nTest against a known reporting period before scheduling. The [ChatGPT and Codex automation guide](/agent-alerts/blog/chatgpt-codex-automations) covers runtime and access requirements. If the chosen environment cannot reach an approved source, narrow the task or resolve access through the appropriate approval process.\n\n## Keep the report small and the authority explicit\n\nDo not delegate financing decisions, spending authority, personnel decisions, or public disclosures to an exception detector. No autonomous payments or financial transactions belong in this workflow. Drafting a recommendation does not authorize sending it to investors, directors, or employees.\n\nUse validated aggregate numbers where possible. Financial summaries still need explicit source and destination approval. Avoid putting cash balances, forecasts, customer names, or confidential strategy in notification text.\n\nA daily check suits a time-sensitive operating exception; monthly financial reporting usually needs a monthly review. Stop temporary watches when the decision is made. Review thresholds after a business model or metric-definition change, and retire checks that repeatedly generate noise.\n\nAgent Alerts is an optional place to display a neutral status when the runtime has a working integration, required tool, and permission. “Business review needs validation” may be enough. Keep detailed evidence in its approved destination, test visible delivery, and use the [Live Activity examples](/agent-alerts/docs/live-activity-examples) to consider whether an ongoing status is useful at all.\n","path":"blog/when-ceos-should-use-automations","url":"https://www.andreas.ink/agent-alerts/blog/when-ceos-should-use-automations","markdownUrl":"https://www.andreas.ink/api/agent-alerts/content?path=blog%2Fwhen-ceos-should-use-automations&format=markdown"},{"id":"agent-alerts-blog-when-engineers-should-use-automations","kind":"blog","slug":"when-engineers-should-use-automations","title":"When Engineers Should Use Automations","description":"Use read-only automations to review CI failures, release candidates, and regression risks with clear evidence, narrow permissions, and stop criteria.","keywords":["Agent Alerts","engineering automations","CI monitoring","release checks","Codex automations","Agent Alerts"],"publishedAt":"2026-11-11","updatedAt":"2026-11-11","content":"# When Engineers Should Use Automations\n\nUse read-only automations to review CI failures, release candidates, and regression risks with clear evidence, narrow permissions, and stop criteria.\n\nEngineers should automate checks when the question stays stable but the evidence keeps changing. “Did this release candidate pass its required checks?” is a useful recurring question. “Is this architecture good?” usually needs a focused review with more context.\n\nStart with read-only access to a named repository and a small report. An automation should reduce the time between a meaningful change and your next decision without creating another stream of warnings to dismiss.\n\n## Three checks worth repeating\n\n### Watch a release candidate, not every build\n\n**Trigger:** A scheduled check during an agreed release window. Use an event trigger only if your account and connected source support it.\n\n**Authorized data:** Check results and release criteria for the exact candidate commit in the named repository.\n\n**Decision:** Report which required checks passed, failed, or remain pending. Link the evidence and identify the commit. A passing result for yesterday’s commit does not clear today’s candidate. Missing or stale results should leave the release unverified.\n\nThis helps the release owner decide whether to investigate or continue their checklist. It must not merge, deploy, or waive a failed check. End the watch when the candidate is replaced or the release window closes.\n\n### Catch repeated CI failures\n\n**Trigger:** A weekday review of newly completed CI runs.\n\n**Authorized data:** Run metadata and permitted, sanitized failure logs from one repository. Avoid fetching logs that could expose credentials or customer data.\n\n**Decision:** Group repeated failure signatures, distinguish new failures from existing ones, and link the affected runs. Describe a suspected flaky test as a hypothesis. One passing rerun does not establish that a failure is harmless.\n\nFor a hypothetical pilot, report a signature only after it appears in three runs, while surfacing a newly failing required check immediately. Tune that rule against actual noise and missed failures. Do not automatically rerun jobs, disable tests, or file issues unless those actions have separate authorization.\n\n### Review regression risks in a bounded diff\n\n**Trigger:** A daily review of commits since the last successful review.\n\n**Authorized data:** The named project’s Git history, changed files, and relevant tests. Record the reviewed commit range so a missed run does not silently leave a gap.\n\n**Decision:** Return a few concrete risks with file references, an explanation of the possible failure, and a suggested test. Distinguish a code-reading concern from a reproduced defect. Report unavailable history or missing test evidence directly.\n\nA separate, explicitly authorized workflow can run selected tests. Keep dependency installation, network access, and code changes outside the initial review.\n\n## A prompt you can adapt\n\n> Every weekday at 9 AM America/New_York, review new completed CI runs for [repository] since the last successful report. Read only the permitted run metadata and sanitized logs. Group repeated failures, identify newly failing required checks, and link each finding to its commit and run. Separate observations from suspected causes. Do not rerun jobs, edit files, post comments, merge, or deploy. Report access failures instead of assuming a healthy state. Keep each report in this chat. End this pilot after five weekday reports so I can review its usefulness.\n\nReplace the placeholder, test manually, and verify the saved schedule. The [automation setup guide](/agent-alerts/blog/chatgpt-codex-automations) covers environment availability and permissions, including local projects that require an awake computer.\n\n## Keep judgment and sensitive details with the engineer\n\nAvoid automating ambiguous architecture decisions, incident command, security exceptions, or release approval. Stop or revise checks that repeatedly produce unactionable findings. Never widen access simply to make a scheduled run succeed.\n\nAgent Alerts can be an optional reporting surface when the running environment has the tools and permission. Send a neutral status such as “Release review needs attention,” with details kept in the approved source. Review [notification behavior](/agent-alerts/docs/notifications) and [Live Activity examples](/agent-alerts/docs/live-activity-examples), then test visible delivery before relying on it.\n","path":"blog/when-engineers-should-use-automations","url":"https://www.andreas.ink/agent-alerts/blog/when-engineers-should-use-automations","markdownUrl":"https://www.andreas.ink/api/agent-alerts/content?path=blog%2Fwhen-engineers-should-use-automations&format=markdown"},{"id":"agent-alerts-blog-when-marketers-should-use-automations","kind":"blog","slug":"when-marketers-should-use-automations","title":"When Marketers Should Use Automations","description":"Automate experiment readiness, campaign pacing, and creative review preparation while respecting measurement windows, data freshness, and spending approvals.","keywords":["Agent Alerts","marketing automations","experiment review","campaign pacing","creative review","Agent Alerts"],"publishedAt":"2026-11-11","updatedAt":"2026-11-11","content":"# When Marketers Should Use Automations\n\nAutomate experiment readiness, campaign pacing, and creative review preparation while respecting measurement windows, data freshness, and spending approvals.\n\nMarketing automations work best when they check whether the evidence is ready for a decision. Daily campaign recommendations create churn when conversions have not matured or the audience changed halfway through the comparison.\n\nStart with one decision, named sources, and a reporting window. Let the automation gather and qualify the evidence while people retain responsibility for creative judgment, publishing, and spending.\n\n## Three useful marketing checks\n\n### Check whether an experiment is ready to review\n\n**Trigger:** A scheduled review after the experiment’s planned measurement window closes.\n\n**Authorized data:** A named analytics report or approved export, the experiment brief, allocation dates, metric definitions, and data-refresh timestamps. Confirm that the running environment can access them before scheduling.\n\n**Decision:** Report whether both variants have comparable cohorts, complete observation windows, and the sample size required by the experiment plan. A hypothetical plan might require seven full observation days per participant; this is not a universal standard. Sample-size requirements should come from the planned analysis, not an arbitrary threshold chosen after seeing results.\n\nFlag changes in channel mix, attribution rules, instrumentation, or eligibility. If the evidence is incomplete, explain what is missing and when another check would be useful. Do not announce a winner just because one conversion rate is higher.\n\n### Prepare a campaign pacing review\n\n**Trigger:** A weekday check at a time when the approved report is normally refreshed.\n\n**Authorized data:** The named campaign export, agreed budget, campaign dates, reporting time zone, and documented conversion delay.\n\n**Decision:** Compare actual spend with the agreed pacing plan. Show the report’s freshness and separate spend observations from provisional conversion outcomes. A hypothetical alert threshold could be spend more than 15% above the planned cumulative amount, but the owner must choose a threshold appropriate to that campaign.\n\nOffer a review recommendation with its assumptions. Do not change bids, pause campaigns, or move budget. Those actions need explicit approval and an available, authorized tool; a reporting workflow does not establish either.\n\n### Assemble the evidence for a creative review\n\n**Trigger:** A weekly check before the team’s creative review.\n\n**Authorized data:** Approved creative IDs, launch dates, channel-specific performance exports, and the current messaging brief. Use aggregated results rather than personal audience records.\n\n**Decision:** Identify assets worth reviewing and link them to supporting evidence. Compare like placements and audience cohorts over equivalent windows. Flag small samples, uneven delivery, and newer assets that have had less observation time.\n\nThe output can suggest questions: Has the message become less relevant? Did audience mix change? Is tracking incomplete? It should not declare creative fatigue from a declining rate alone or publish replacement copy without review.\n\n## A prompt you can adapt\n\n> Every Tuesday at 10 AM America/New_York, review [approved experiment report] against [experiment brief]. Report the refresh timestamp, measurement window, cohort definitions, and whether the planned sample-size and observation-window requirements are met. Identify tracking or allocation changes that limit comparison. Summarize the evidence and recommend review, continued observation, or investigation. Do not invent missing results, declare a winner without the planned analysis, publish content, contact anyone, or change spend. Keep the report in this chat. Stop after the experiment’s recorded end date and report any unresolved evidence gaps.\n\nReplace the sources and test access manually. The [automation setup guide](/agent-alerts/blog/chatgpt-codex-automations) explains scheduling and environment requirements without assuming a particular marketing integration exists.\n\n## Choose a cadence that respects the data\n\nAvoid repeated checks before a source refresh or before conversion windows mature. Stop when the experiment closes, the campaign ends, or the source definition changes enough to invalidate comparison. Repeated missing data should prompt a reporting fix, not increasingly confident guesses.\n\nAgent Alerts is an optional place to show “Campaign review ready” when tools and permission exist. Keep confidential budgets, customer details, and unpublished creative out of Lock Screen text. Test [notifications](/agent-alerts/docs/notifications); use [interactions](/agent-alerts/docs/interactions) only within the actions the connected workflow actually supports and the user has authorized.\n","path":"blog/when-marketers-should-use-automations","url":"https://www.andreas.ink/agent-alerts/blog/when-marketers-should-use-automations","markdownUrl":"https://www.andreas.ink/api/agent-alerts/content?path=blog%2Fwhen-marketers-should-use-automations&format=markdown"}],"mcpUrl":"https://www.andreas.ink/api/agent-alerts/content/mcp"}