elizaos--eliza/plugins/plugin-native-macosalarm/README.md

@elizaos/macosalarm

macOS native alarm scheduling for Eliza agents via UNUserNotificationCenter.

What it does

This plugin adds the ALARM action to an Eliza agent, enabling it to:

• Set calendar-trigger alarms that fire as macOS system notifications (with sound).
• Cancel pending alarms by ID.
• List all pending alarms registered by the agent.

Alarms are delivered through macOS's native UNUserNotificationCenter API. A self-contained Swift CLI (swift-helper/main.swift) is compiled to a binary at bin/macosalarm-helper during the build step. The Eliza runtime spawns this binary via stdin/stdout JSON IPC — no network calls, no third-party services.

Platform support

macOS (darwin) only. The plugin is auto-enabled on darwin ("autoEnable": "darwin"). On any other platform the action's validate hook returns false and no alarms are attempted.

Requirements

• macOS with swiftc available (Xcode Command Line Tools).
• Node.js >= 24.
• The package must be built before use: bun run build compiles both the TypeScript and the Swift helper binary.

Installation

The plugin is part of the elizaOS monorepo. In your agent character config, reference the package name @elizaos/macosalarm (it auto-enables on darwin). For manual loading:

import macosAlarmPlugin from "@elizaos/macosalarm";
// add to your runtime's plugins array

Build

bun run --cwd plugins/plugin-native-macosalarm build

This runs tsc --noCheck and then swiftc swift-helper/main.swift -O -o bin/macosalarm-helper.

Configuration

Env variable	Default	Purpose
ELIZA_MACOSALARM_HELPER_BIN	bin/macosalarm-helper (relative to package root)	Override the path to the compiled Swift binary

No other configuration is required.

Capabilities

ALARM action

The ALARM action has three subactions. The subaction is inferred from the message text when not explicitly provided.

Subaction	Required params	Description
set	timeIso, title	Schedule a new alarm. timeIso must be an ISO-8601 timestamp. body, sound, and id are optional.
cancel	id	Remove a pending alarm by its ID (returned from a prior set).
list	—	Return all pending macOS alarms.

Example interactions:

• "Set an alarm for 7am tomorrow" — schedules via set.
• "Cancel alarm alarm-abc123" — cancels via cancel.
• "List my pending alarms" — lists via list.

Keyword matching covers English and several other languages (Spanish, French, German, Chinese, Japanese, Korean, Vietnamese).

Permissions

On first use of set, macOS will prompt the user to allow notifications from the process. If the user denies this permission, alarm scheduling will fail with a permission-denied error.

Role gate

The ALARM action requires the agent's user to have at minimum the ADMIN role.

Limitations

• macOS only — no Windows or Linux support.
• The Swift binary must be compiled locally; pre-built binaries are not bundled in the npm package.
• UNUserNotificationCenter requires the helper to run from a signed app bundle. Invoked as a bare CLI it throws an NSInternalInconsistencyException (bundleProxyForCurrentProcess is nil); packaging/signing is owned downstream.