---
title: Notifications
description: How a routine gets a person's attention. The Inbox and Today today, the workspace notification setting, quiet hours, and the derived notification feed (since 0.5.0).
sidebar:
  order: 9
---

## What it is

A notification is anything that tells a person a routine needs them. In RoutineOS the primary channel is the Desk itself: the Inbox and the Today page. A workspace setting records whether people also want push notices, and when they do not want to be disturbed.

## Why it exists

A routine that runs twice a week and writes 40 records should not ask for 40 looks. The Inbox is capped per run (`max_inbox_per_run`), and Today shows only what is unread or undone. Notifications point at a short list on the Desk; they do not replace it.

## How it works

### The Inbox

Runs write Inbox messages of four kinds:

| Kind | Means |
|---|---|
| `match` | A strong fit a person should look at |
| `alert` | A change worth knowing, for example at a starred company |
| `proposal` | A suggested setting or definition change |
| `approval` | An action waiting behind a gate |

The write contract writes at most `max_inbox_per_run` messages per run and records `inboxSuppressed` (over the cap) and `inboxFiltered` (a match whose linked records were all dropped). Proposals from the learning step are placed at the front of the run's inbox so the cap never drops them.

### Today

Today collects match and alert messages that are unread or undone for this viewer, partial or failed runs not yet acknowledged, and open gates. Read, done and acknowledged state is per viewer, under `data/users/<viewer>/state/`.

### The workspace setting

`settings/workspace` holds:

| Key | Values | Seed default |
|---|---|---|
| `notifications` | `inbox` (Inbox only) or `push` (Inbox plus push) | `inbox` |
| `quietHours` | `{from, to}` | `{"from": "", "to": ""}` |

The Desk Settings page offers "Inbox only" and "Inbox plus push", and under quiet hours says: "No push between these times. Stored. No producer acts on this yet." The setting records a preference. RoutineOS does not ship a push transport: the registry lists push as one-way with the reply path unverified, and the infrastructure research for these docs found no native push for Claude scheduled tasks. A routine that honours the push preference sends through a channel it declares (see [Notification channels](/infrastructure/notification-channels)).

> Since 0.5.0: a **notifications bell** in the top bar with an unread count, and a feed derived from the store with no new producer writes: new Inbox items, gates waiting, gates near timeout (under 6 hours), failed or late runs, and cap-reached alerts. Read state reuses `data/users/<viewer>/state/read/<id>`. The panel has All and Unread tabs, Mark all read, and a Preferences link to the workspace notifications setting. Shortcut: `n`.

## Worked example

Hiring Signals finds 12 roles on a Thursday run. Four are strong fits. `max_inbox_per_run` is 5. The learning step raised one proposal ("Add hydrogen to title_keywords"). The run's inbox holds the proposal first, then the four matches: five messages, none suppressed. Today shows the four matches until a person marks them read or done.

## Common pitfalls

- **Raising the cap to see everything.** Every record is on Browse already. The cap protects attention; raise it only when people keep missing strong fits.
- **Putting the cap in the prompt only.** The contract applies `max_inbox_per_run`. The prompt should stay inside it too, but code is what holds it.
- **Expecting push to work because the setting says push.** The setting is a preference, not a transport.

## Related

- [The Desk: Today](/desk/today)
- [The Desk: Inbox](/desk/inbox)
- [Notification channels](/infrastructure/notification-channels)