BuilderIO/agent-native / packages/core/src/templates/default/.agents/skills/notifications
notifications
VerifiedIn-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).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.5 KB |
SKILL.md
View on GitHub---
name: notifications
description: >-
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
| Tool | Purpose |
| -------------------- | ------------------------------------------------------------------------ |
| `notify` | Send a notification (severity + title + optional body/metadata/channels) |
| `list-notifications` | Show recent notifications for the current user |
## Sending
```
notify --severity info --title "Booking confirmed" --body "Jane at 3pm"
```
| Severity | When |
| ---------- | ----------------------------- |
| `info` | FYI / progress / confirmation |
| `warning` | Something to look at soon |
| `critical` | Needs 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
| Channel | How | Requires |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| `inbox` | INSERT → drives bell UI | (always on) |
| `webhook` | POST JSON to `NOTIFICATIONS_WEBHOOK_URL` (+ optional `NOTIFICATIONS_WEBHOOK_AUTH`); both support `${keys.NAME}` + URL allowlists from the ad-hoc-keys system | env var set |
The webhook channel resolves `${keys.NAME}` server-side — the raw value never enters the agent context.
## Registering a Custom Channel
```ts
// 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
```tsx
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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |