Appearance
Background Notifications (Android)
Clusto's in-app notifications only fire while the app is open and connected. On Android, background notifications close that gap: the app briefly wakes on a timer, connects to your cluster, and raises a native notification for anything that happened while it was closed or backgrounded - a finished terminal agent or durable chat, a scheduled task that succeeded or failed, or a session waiting on you.
This is opt-in and battery-friendly. Clusto does not hold a constant connection; it connects for a moment roughly every 15 minutes, checks for missed alerts, and disconnects.
Turning it on
Open Settings -> Notifications on the Android app. Under Background notifications (this device), enable Check for missed notifications while the app is closed.
The toggle works only on Android, where the native scheduling support exists; elsewhere the section is shown greyed out. On desktop and in the web client the app relies on the normal in-app / OS alerts while it is running (see Agent Waiting Marker), so there is no equivalent toggle there.
If alerts do not arrive, open Settings > Node Doctor. Its This device row shows whether system notification permission, alert popups and Android background checks are on, and Send test notification raises a sample alert. See Node Doctor.
Unencrypted LAN addresses need your OK
The background check is a plain HTTP request that carries your token. It goes out without asking only where that is safe: this device (loopback), your Tailscale network (100.64.0.0/10, fd7a:115c:a1e0::/48, *.ts.net), or https:// to a node with a certificate for its DNS name. When the profile can only reach a node over plain HTTP on another network (a 192.168.x.x address, say), the check would send the token in clear on every poll, so Clusto skips it and Settings -> Notifications shows that background notifications are paused, with an Allow unencrypted polls to ... button per host.
Allowing a host is saved with the profile (it syncs to your own devices, never to a team vault) and can be undone with Stop unencrypted polls. The node must also accept unencrypted connections from that network ([transport] plaintext_networks), or every poll is refused with 403. The refusal arrives after the request, headers included, has been sent, so a poll to a network the node refuses still exposes the token once per poll. An allowed address is polled on whatever network the phone is on, and a private address such as 192.168.1.5 can belong to another device on a cafe or office network, which would then receive your token. Prefer Tailscale or a node certificate. The Android check cannot pin a node's key like the app does, and it cannot use the Clusto Tunnel, so a profile that reaches a node only through the tunnel is not polled. See Node Identity & Pairing.
A prompt you have already answered no longer reaches the background check: once the agent continues, the alert is marked answered in the notification center and the phone does not raise it.
What you get notified about
While the app is closed, a background check surfaces the same events the app would have alerted you to live:
- A terminal agent or durable chat finished - a session went idle or a chat reply became ready.
- A scheduled task succeeded or failed - honouring the per-task Notify on success / Notify on failure opt-ins (see Tasks). A task with neither flag set stays silent.
- A session is waiting for you - the same "needs input" signal that drives the
?marker (see Agent Waiting Marker). - A new report - posted by an agent or script to Reports, filtered by the report rules in Settings -> Notifications -> Reports (a default rule plus per-project overrides). Tap it to open the report.
- A GitHub pull request alert - a review requested from you, failed checks on a pull request you wrote, or one of your pull requests approved, merged or closed (see GitHub). Tap it to open the pull request. Each kind has its own switch under Settings -> Notifications.
Each notification carries a title and body and, where relevant, targets the terminal session or chat it relates to. Tap the notification itself to open that target; Clusto does not add a separate action button on Android.
Timing: expect up to ~15 minutes
The ~15 minute cadence is a floor imposed by Android, not a setting. Clusto uses an inexact repeating alarm, which Android is free to delay and batch, especially under Doze (the OS's idle power-saving mode). So a missed alert can arrive up to about 15 minutes late, sometimes more if the device has been idle for a long stretch.
This is a deliberate trade-off: a constant push connection would drain the battery, while a periodic wake keeps power use negligible. If you need to-the-second alerts, keep the app open in the foreground, where in-app notifications fire immediately.
No double alerts while another client is connected
If any Clusto app is connected to the cluster - say Clusto is open on your desktop - that client already receives every alert as a live push. The background poll stays silent for as long as such a client is connected, so your phone does not buzz for things you are already looking at elsewhere. The poll cursor still advances during the quiet period; those alerts are considered delivered and do not arrive late once the other client disconnects.
Two details:
- Only app clients count. A transient
clustoCLI invocation does not suppress background notifications. - Answering a waiting session clears its pending
attentionrecords from the durable log immediately, so a prompt you resolved on the desktop cannot re-notify your phone on the next poll even if the desktop disconnects right after.
Battery saver: background idle sleep (mobile)
Related to, but separate from, background notifications: on phones and tablets the app has a battery saver (Settings -> This device -> Battery, touch devices only). When the app has been in the background for the configured idle window (default 15 minutes), it disconnects from the daemon - stopping the Android keep-alive foreground service, its ongoing "Keeping your sessions connected" notification, and the WebSocket keepalive pings that would otherwise hold the radio awake. The app reconnects automatically the moment you return to it. After the connection and initial data recovery complete, Clusto keeps the connect/reconnect loading indicator visible only briefly to avoid a flash. The artificial minimum is capped at 750 ms, so recovered content becomes usable promptly after reopening or resuming the app.
On Android the countdown runs natively (a one-shot AlarmManager alarm), because Android freezes a backgrounded WebView's JS timers - a JS-only timer would never fire exactly when it matters. The alarm is a non-wakeup alarm: if the device is in deep sleep at the deadline, the disconnect happens on the next natural wake instead of waking the CPU just to save power.
While asleep the app holds no connection, so enable background notifications if you still want missed-alert delivery during that window.
Cluster-wide coverage
The background check polls a single node - whichever one your app's active profile points at. That node aggregates missed notifications from the whole cluster before answering, so a task failure, an idle terminal agent, or a completed chat on any node still reaches your phone through the one node you poll. You do not need to poll every node individually.
How it works
The feature has two halves: a durable notification log the daemon keeps, and a native Android poller that reads it.
Daemon: durable notification log
Every alert the daemon fires is appended to a durable log (a SQLite notifications table) so a client that was offline when the alert fired can still see it on its next poll. The log is bounded: rows older than 7 days, or beyond the newest 500, are pruned after each insert.
Each record carries a stable id (clients dedupe on it across polls), the firing time in Unix milliseconds, a machine-readable kind, an optional session_id tap-to-open target, the firing node_id, and a title / body. Terminal targets store a session UUID. Chat targets store chat:<uuid> so opening the notification routes to the originating chat.
The kind is one of:
kind | Meaning |
|---|---|
agent_idle | A terminal agent went idle or a durable chat reply completed |
attention | A session is waiting for the user (the ? state) |
task_success | A scheduled task completed with exit 0 |
task_failure | A scheduled task failed (non-zero exit or timeout) |
report | A new report was posted to Reports |
github_review_requested | A review was requested from you on a GitHub pull request |
github_checks_failed | Checks failed on a pull request you wrote |
github_pull_update | A pull request you wrote was approved, merged or closed |
HTTP endpoint
The Android poller reads the log over a small authenticated HTTP endpoint:
GET /notifications?since_ms=<unix_ms>- Authenticate with the daemon token as
Authorization: Bearer <token>. The cluster token is also accepted. A?token=query parameter is not accepted, so the credential never lands in access logs or proxies. - The response is
{ "now_ms": <server_time>, "items": [ ...NotificationRecord ] }, whereitemsare the notifications fired aftersince_ms, aggregated across the cluster. - The client persists the returned
now_msas its nextsince_mscursor, so each poll only returns what is new since the previous one. - While any app client is connected anywhere in the cluster,
itemsis empty (see "No double alerts" above);now_msstill advances the cursor. - A device can switch off the GitHub alert kinds for its own poll by adding
github_review_requested=off,github_checks_failed=offand/orgithub_pull_update=offto the query, for exampleGET /notifications?since_ms=<unix_ms>&github_review_requested=off. The Azure DevOps and factory (factory_waiting_owner,factory_pull_ready) kinds can be muted the same way. No other kind can, and only the valueoffmutes. The app sets them from the per-device switches under Settings -> Notifications. - The device's report rules ride along on the same poll:
report_default=all|warnings|errors|offsets the default rule andreport_projects=<uuid>:<mode>,...adds per-project overrides. A poll withoutreport_defaultreceives every report alert.
The same aggregation is available over the WebSocket protocol via ClientMessage::GetNotifications { since_ms } -> ServerMessage::Notifications { items, now_ms, active_clients }, which the polled node uses to fan out to its peers: each peer answers with its own log slice and its local count of connected app clients, and the polled node merges the items and sums the counts (see Protocol).
Android native side
The native scheduling is generated into the Android project at build time. It wires up:
- An AlarmManager inexact-repeating alarm that wakes the app roughly every 15 minutes.
- A BroadcastReceiver (
ClustoBackgroundNotifyReceiver) that runs on each alarm: it does theGET /notificationsrequest with the stored cursor and posts a native notification for each new item. - A boot receiver that re-arms the alarm after the device reboots, so the feature keeps working across restarts without reopening the app.
Configuration (enabled flag, base URL, token, and the since_ms cursor) lives in Android SharedPreferences, written when you toggle the setting and read by the receiver on each wake.