Permissions

List permissions in manifest.json. Users see them on the install sheet. Sensitive ones are also asked the first time you use them, in a prompt showing your justifications text. Users can turn any of them off at any time in Settings → Plugins, so plan for “no”.

"permissions": ["network", "location"],
"network": { "domains": ["api.open-meteo.com"] },
"justifications": { "location": "Weather where you are." }

Limits

• network: https only, only your domains, no cookies, ≤ 10 s, ≤ 5 MB per response, 60 requests a minute. Keep secret API keys out of your package, because reviewers and users can read them.
• notifications: 6 an hour, titled with your plugin’s name.
• peek: one a minute and 6 an hour; title ≤ 48 and detail ≤ 80 characters; icon is one of the pill icons (PILL_ICONS). Your plugin’s name is shown under it. It doesn’t show while the panel is open, and the user can turn plugin pop-ups off in Settings, so treat it as a nudge for news worth a glance (rain soon, a review requested), never as the only place something is said. Ongoing status belongs in the pill.
• alarms: 100 scheduled per plugin, title ≤ 64 and body ≤ 240 characters, at from an hour ago to 400 days ahead, 60 set/cancel calls a minute.
• files: ≤ 5 MB per file. Picking works only while the user is using your widget. A picked file stays readable by handle until the user removes it.

Running in the background

Normally your frames are destroyed when the notch collapses and reloaded when it opens. Two permissions change that for your tile:

• background keeps it running whenever it’s on the board. Declare a CPU budget, and say why in justifications:

  "permissions": ["background"],
  "background": { "budget": "low" },
  "justifications": { "background": "Checks your build status every minute." }

  Budget	CPU while collapsed (share of one core)
  low	2%
  medium	5%
  high	10%

• audio:play lets you play sound (autoplay is allowed). With network too, <audio> may stream from your network.domains (still https only; fetch stays blocked). Call notch.audio.setPlaying(true) when playback starts and false when it stops: while you’re playing, that frame (your tile, or your expanded view) keeps running when the notch collapses or the user goes back to the board, on the medium budget (or your background budget if you have one). If the frame reloads or is paused, it counts as stopped. Tile and expanded view are separate pages: if both can play, keep them in step (e.g. through notch.storage.plugin) so the user doesn’t hear two streams.

While collapsed, visibility is false and the tile isn’t drawn, so requestAnimationFrame doesn’t run: use timers, and do as little as you can. Going over your budget for 10 seconds in a row pauses your plugin until the user resumes it. While the notch is open, every plugin’s limit is 10% of a core.

Checking answers

const ctx = await notch.ready();
if (ctx.permissions.location === "denied") showCityPicker();
notch.on("permissions", (p) => { /* the user changed something */ });

ask means the user hasn’t answered yet. The first call asks them.

Alarms

With alarms you schedule alerts and the app rings them: at at it covers the screen with an alert (your plugin’s name, your title and body) and plays a sound, even while the notch is closed and your plugin isn’t running. The user can Dismiss or Snooze (5, 10 or 15 min; with startsAt, never past it, plus “Until it starts”). With startsAt the alert counts down to it (“Starts 10:00 AM · in 10 min”). With completable: true it also offers Mark done: the alarm becomes done with completed: true, and notch.alarms.onChange tells a running plugin. If nobody answers within a minute it counts as missed and, with repeatEveryMinutes, rings again that much later, up to maxRepeats times (default 3).

await notch.alarms.set({
  key: "standup-2026-10-22",          // yours; setting it again replaces it
  at: Date.parse("2026-10-22T09:50"),
  title: "Standup",
  body: "Room 4",
  startsAt: Date.parse("2026-10-22T10:00"),
  completable: true,
  repeatEveryMinutes: 5,
});
const mine = await notch.alarms.list(); // state: scheduled | ringing | done | missed
notch.alarms.onChange((all) => {
  for (const a of all) if (a.completed) markDone(a.key);
});
await notch.alarms.cancel("standup-2026-10-22");

Alarms ring only on this PC and aren’t synced. An alarm that came due while the app was closed rings when it starts if it’s at most an hour late, and is missed otherwise. Dismissed and missed alarms stay in list() for a week, so you can tell what happened.