Skip to content

BuilderIO/agent-native / packages/core/src/templates/default/.agents/skills/notifications

notifications

Unverified

In-app notifications primitive with pluggable server-side channels. Use when the agent needs to surface progress, alerts, or completions to the user — both in-app (bell + toast) and out-of-band (webhook, Slack, custom).

Notifications

notify() is the framework's "tell the user something" primitive. Every call persists a row to the inbox (drives the bell UI) and fans out to any registered server-side channels. Channels follow the same pluggable-provider pattern as tracking — register at startup, notify() fans out, errors are isolated.

Use for: agent progress milestones, automation triggers firing, background job completions, critical errors. Don't use for chat replies — those go through the conversation.

Tools

ToolPurpose
notifySend a notification (severity + title + optional body/metadata/channels)
list-notificationsShow recent notifications for the current user

Sending

notify --severity info --title "Booking confirmed" --body "Jane at 3pm"
SeverityWhen
infoFYI / progress / confirmation
warningSomething to look at soon
criticalNeeds immediate attention

Optional: --metadataJson '{"threadId":"abc"}', --channels inbox,webhook (omit to run all registered).

Delivery

notify() always inserts into the notifications table (unless channels explicitly excludes inbox), then fans out to every registered channel in parallel (best-effort; a failing channel doesn't block others). Finally it emits notification.sent on the event bus so automations can chain — e.g. "when a critical notification fires, also page on-call."

Built-in Channels

ChannelHowRequires
inboxINSERT → drives bell UI(always on)
webhookPOST JSON to NOTIFICATIONS_WEBHOOK_URL (+ optional NOTIFICATIONS_WEBHOOK_AUTH); both support ${keys.NAME} + URL allowlists from the ad-hoc-keys systemenv var set

The webhook channel resolves ${keys.NAME} server-side — the raw value never enters the agent context.

Registering a Custom Channel

// server/plugins/notifications-slack.ts
import { registerNotificationChannel } from "@agent-native/core/notifications";

export default () => {
  registerNotificationChannel({
    name: "slack-ops",
    async deliver(input, meta) {
      await fetch(process.env.OPS_SLACK_WEBHOOK!, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          text: `*${input.severity}* — ${input.title}`,
          owner: meta.owner,
        }),
      });
    },
  });
};

Names are unique — re-registering replaces. deliver() must be best-effort; a thrown error is logged and ignored. Do NOT call notify() from inside a channel (recursion).

HTTP API

Mounted at /_agent-native/notifications/* by core-routes-plugin, all session-scoped:

  • GET /notifications?unread=true&limit=50&before=<iso>
  • GET /notifications/count
  • POST /notifications/:id/read
  • POST /notifications/read-all
  • DELETE /notifications/:id

UI

import { NotificationsBell } from "@agent-native/core/client/notifications";

<NotificationsBell browserNotifications />;

Bell icon + unread badge + lazy-loaded dropdown. Pass browserNotifications to also fire system new Notification(...) popups for items that arrive after mount (dedups by id, renders an "Enable" prompt until permission is granted, silently no-ops on denied / unsupported). Styled with shadcn tokens — adapts to the host theme.

Related

  • automations — event-triggered bodies can call notify.
  • secrets — ${keys.NAME} substitution + URL allowlists powering the webhook channel.
  • tracking — analytics; separate concern, don't route through notifications.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 465kUpdated Claude CodeCodexVerifiedInstall
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 465kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall