Files
pipelines/docs/notifications.md
alan 80022ea41a Keep observing chats with an in-flight turn after the last client leaves
Chat attention notifications (questions, approvals, finished replies) come
from a session's event stream, which the hub only read while a room existed;
detach destroyed the room when the last client left, so a turn that finished
or asked with the app closed notified nobody.

A room whose last client leaves now stays observing, unattended, while its
turn is in flight or it holds an unanswered question/approval, and is torn
down when the turn ends (or after 6h for a stuck turn); at most 16 such rooms.
At server start, recently used open sessions whose harness reports a running
turn (OpenCode /api/session/active, Codex thread/turns/list) are observed
again so their reply still notifies. Settings, dedupe and app_notifications
recording are unchanged.
2026-11-02 16:07:42 +00:00

105 lines
4.3 KiB
Markdown

# Notifications
The server records every notification once and delivers it two ways:
1. **In the Pipelines app** (Android, and the web page while it is open), over
the app's own connection. No ntfy app is needed.
2. **ntfy** (optional fallback), for devices that still use the ntfy app.
The same settings decide what is sent on both paths.
## What notifies
| Event | When |
| --- | --- |
| Run needs your decision | a run reaches a human decision stage (runs not set to Silent) |
| Run failed / succeeded | runs started with **Notify me** (`--notify on`), or every run when **Notify when any run ends** is on |
| Stage hook | a stage's own `notify` block fires ([ntfy reference](ntfy.md)) |
| Chat needs you | a chat asks a question or requests approval |
| Chat replied | an assistant turn ends (off by default) |
Each event notifies once. Opening or dismissing it on one device clears it on
the others.
Chat events do not need the chat to be open. When the last app or browser
leaves a chat whose turn is still running, or which has an unanswered question
or approval, the server keeps watching it until the turn ends and nothing is
left to answer, so "Chat needs you" and "Chat replied" still arrive with the
app closed. A client that reopens the chat meanwhile joins the same watch, so
nothing is announced twice. Idle chats are not watched.
Limits:
- At most 16 chats are watched with no client attached; a further one is not
(queued messages are always delivered regardless).
- A turn that never reports its end stops being watched after 6 hours.
- After a server restart, the 32 most recently used open chats (used in the last
24 hours) are asked whether a turn is still running, and those that are are
watched again. This works for OpenCode and Codex, which keep running across a
Pipelines restart. A Claude Code turn runs inside the server process and ends
with it, so there is nothing to resume.
## Settings
In the app, **Settings**:
**Notifications** asks for the platform's notification permission.
**Notifications in Pipelines** (Android only):
- **Receive notifications in Pipelines**: starts a background service that
keeps its own connection to the server and posts notifications. Android shows
a quiet "Pipelines is connected" notification while it runs. It restarts
after a reboot or an app update.
- **Status**: the service's connection state.
- **Allow notifications**: shown when Android is blocking Pipelines
notifications.
- **Allow background delivery**: asks Android to exempt Pipelines from battery
optimisation so delivery stays instant while the phone is idle. Grant it.
**Phone notifications** (stored on the server, shared by every device):
| Setting | Default |
| --- | --- |
| Notify when any run ends (otherwise only runs started with **Notify me**) | off |
| Chat needs your answer or approval | on |
| Chat reply finished | off |
| Also send to ntfy (for devices that still use the ntfy app) | on |
Turning **Also send to ntfy** off stops publishing to ntfy; the app still
receives everything.
Per run, choose **Notify me**, the default (auto), or **Silent** when starting
it. From the CLI: `pipelines run … --notify on|auto|off`.
## The web app
The web page shows notifications only while it is open and the browser allows
them. Closed-browser web push is not implemented.
## ntfy (optional)
`./install` builds and runs ntfy on port 8090 with a private `pipelines` topic.
The installer prints the subscription details at the end, and
`pipelines doctor` repeats them (`Phone server … · topic: pipelines ·
username: phone-reader`).
To subscribe from the ntfy app:
1. Add a server: the ntfy address (default `http://<LAN IP>:8090`, or the
`--ntfy-url` you installed with). Off your home network, use a VPN such as
Tailscale.
2. Sign in as `phone-reader`. A freshly created account uses the web sign-in
password; an account kept from an earlier install keeps its old password.
3. Subscribe to the topic `pipelines`.
A tap opens `pipelines://run/<id>` or `pipelines://chat/<id>` in the Android
app; the **Open in browser** action opens the same page on
`PIPELINES_WEB_PUBLIC_URL`.
Notifications already shown by the ntfy app cannot be retracted by the server;
swipe them away there.
See [ntfy reference](ntfy.md) for stage `notify` hooks, explicit ntfy stages,
the app notification protocol and network troubleshooting.