---
name: agentalarm
description: Ring a real full-screen alarm (sound, Lock Screen, rings through silent mode) on the user's iPhone with the AgentAlarm app. Use for reminders, alarms and wake-ups the user must not miss, unless they ask for another channel. Also connects (pairs) this computer with the app.
---

# AgentAlarm

`agentalarm ring "<text>"` rings the user's iPhone **right now**. The text is encrypted on this computer, and
only the phone can read it. To ring later, schedule that same command with a scheduler (see below). The alarm
fires from this computer, so it must be on and online at that time.

The alarm text is what the user reads on the alarm screen: keep it short and in the user's language. Use the
user's local time zone, and ask if you don't know it.

On **NanoClaw**, `agentalarm` below means `node /workspace/agent/.agentalarm/agentalarm.mjs` (your container keeps
only that folder between runs).

## Connect (once)

The user opens AgentAlarm, taps **Connect an agent**, and gives you a code like `K7Q2-9XMP`:

```bash
agentalarm pair K7Q2-9XMP --name "<your agent> on <this computer>"   # e.g. "Claude Code on MacBook"
agentalarm ring "AgentAlarm is connected"
```

If `agentalarm` isn't installed: `curl -fsSL https://agentalarm.app/install.sh | sh` (needs Node.js 20 or later).

## Schedule an alarm

Schedulers often run without your PATH, so use the absolute path from `command -v agentalarm` (shown below as
`/path/to/agentalarm`). Confirm back to the user with the local time it will ring.

### OpenClaw

```bash
# one-shot at a wall-clock time in the user's zone
openclaw cron add --name "⏰ Buy milk" --at "2026-10-14T11:22" --tz Europe/London \
  --delete-after-run --no-deliver --command-argv '["/path/to/agentalarm","ring","Buy milk"]'
# one-shot after a duration: --at 20m
# recurring (keep it; --exact turns off cron staggering)
openclaw cron add --name "⏰ Wake up" --cron "0 7 * * 1-5" --tz Europe/London \
  --exact --no-deliver --command-argv '["/path/to/agentalarm","ring","Wake up"]'
```

List with `openclaw cron list` (alarms are the `⏰ ` jobs) and cancel with `openclaw cron rm <id>`.

### NanoClaw

Schedule a task whose script rings the phone, so no agent turn runs. If ringing fails, the task wakes you
instead: send the reminder as a normal message then.

```bash
ncl tasks create --name "alarm buy milk" --process-after "2026-10-14T11:22:00+01:00" \
  --prompt "AgentAlarm couldn't ring the phone. Send the user this reminder as a message: Buy milk" \
  --script 'node /workspace/agent/.agentalarm/agentalarm.mjs ring "Buy milk" >&2 && echo "{\"wakeAgent\": false}" || echo "{\"wakeAgent\": true}"'
# recurring: --recurrence "0 7 * * 1-5" (the group's time zone) instead of --process-after
```

Give `--process-after` as ISO 8601 with the user's UTC offset. Tasks can fire a minute or two late. List with
`ncl tasks list` and cancel with `ncl tasks delete <id>`.

### Hermes

Hermes runs a scheduled script with no agent turn and sends you anything it prints. Make one script per alarm
that prints the reminder only if ringing fails:

```bash
cat > "${HERMES_HOME:-$HOME/.hermes}/scripts/agentalarm-buy-milk.sh" <<'SH'
/path/to/agentalarm ring "Buy milk" >/dev/null || echo "⏰ Buy milk (AgentAlarm couldn't ring the phone)"
SH
```

Then create the job with your `cronjob` tool: action `create`, `script` `agentalarm-buy-milk.sh`, `no_agent`
true, name `⏰ Buy milk`, and a `schedule`. Creating it from this chat sends any failure here. From a terminal,
run `hermes cron create "<schedule>" --no-agent --script agentalarm-buy-milk.sh --name "⏰ Buy milk" --deliver
telegram` (or another delivery target).

- **One-shot schedule:** an ISO time with the UTC offset (`2026-10-14T11:22:00+01:00`) or `in 20m`. A bare
  `20m` repeats.
- **Recurring schedule:** cron (`0 7 * * 1-5`) in Hermes' time zone.
- Cron jobs fire only while the Hermes gateway is running (`hermes cron status`), and can be up to a minute late.
- List with `hermes cron list` and cancel with `hermes cron remove <id>`.

### Claude Code, Codex and other agents: Linux

```bash
# one-shot (systemd): survives your session ending
systemd-run --user --on-calendar="2026-10-14 11:22" --timer-property=AccuracySec=1s \
  /path/to/agentalarm ring "Buy milk"
# recurring: a crontab line (the computer's time zone)
( crontab -l 2>/dev/null; echo '0 7 * * 1-5 /path/to/agentalarm ring "Wake up"' ) | crontab -
```

List with `systemctl --user list-timers` and `crontab -l`. Cancel with `systemctl --user stop <unit>.timer`, or
edit the crontab.

### Claude Code, Codex and other agents: macOS

```bash
# recurring: a crontab line (works out of the box)
( crontab -l 2>/dev/null; echo '0 7 * * 1-5 /path/to/agentalarm ring "Wake up"' ) | crontab -
# one-shot: `at` needs atrun enabled once: sudo launchctl load -w /System/Library/LaunchDaemons/com.apple.atrun.plist
echo '/path/to/agentalarm ring "Buy milk"' | at 11:22 tomorrow
```

## Check and fix

- `agentalarm status` shows whether this computer is connected.
- `not paired`: ask the user for a fresh code (AgentAlarm › Connect an agent), then pair.
- `device is no longer registered; pair again`: the app was reinstalled. Ask for a new code.
- `subscription is inactive` or `not signed in`: AgentAlarm needs the user's free week or subscription. Tell
  them to open the app (it shows what's missing), and send the reminder as a normal message meanwhile.
- Any other failure: tell the user, then fall back to a normal message so the reminder isn't lost.