# Agent Notifications

> Tells you when an agent finishes a turn or needs your input, wherever you are.

- Area: Desktop, mobile and web
- Plans: All plans
- Last checked against the product: 2026-10-01
- Web page: https://agentsroom.dev/docs/agent-notifications

## What it does

Tells you when an agent finishes a turn or needs your input, wherever you are. In the app: unread badges per project in the sidebar (**3 unread agents**, **1 agent waiting for input**) and a hover preview of the last line each agent produced. Outside the app: a native desktop notification (macOS, Windows, Linux) that opens the exact agent when clicked, an unread count on the dock or taskbar icon, optional sounds, and a push to the paired phone when you are not really at the computer. Long dev commands can notify you too when they finish.

## Where to find it

- Sidebar: badge and preview on each project; the needs-input pill in the title bar lists the agents waiting.
- Settings > **Notifications**: sounds and terminal command alerts.
- Settings > **Mobile**: **Send notifications to phone**, and **Agent notifications on the phone** (All / Needs you / Off).
- Project settings > **Agents**: **Agent notifications on the phone** for that project's agents (Inherit / All / Needs you / Off).
- Right-click an agent > **Phone notifications**: that one agent (Project default / All notifications / Only when it needs you / Off).
- Phone: Settings > **Notifications** (system permission) and **Agents and terminals** (Follow desktop / Always / Never); long-press an agent > **Phone notifications** for that agent.

## How to use it

1. Leave the sounds and system notifications on (default) and let the operating system ask for permission the first time.
2. Click a desktop notification: AgentsRoom comes forward on that agent, in that project.
3. To be notified on the phone, pair it and tick **Send notifications to phone**. A push is sent only when you are not actively using the computer (window in front plus recent keyboard or mouse activity means no push). Each push shows the agent's avatar as the sender and the project as subtitle; several outputs from the same agent within five seconds are grouped into one, and one event is announced once whatever the number of AgentsRoom windows you have open.
4. On the phone, **Agents and terminals** lets the phone decide for itself: **Always** notifies even while you work at the computer, **Never** silences that computer.
5. To choose WHICH agents reach the phone, set a level: **All notifications** (every finished turn, question and message), **Only when it needs you** (only an agent waiting for your answer, or a message it sends you on purpose) or **Off**. The narrowest level wins: the agent's own (right-click menu, or long press on the phone), then the project's, then the account's. Typical set-up for a busy pipeline: the project on **Off**, and the one agent that coordinates it on **All notifications**. Throwaway agents (backlog tickets, team steps, quick agents) have no level of their own and follow the project.

Agents can also message you on purpose: an agent working without you (a scheduled run keeping a board moving, a long pipeline) calls the `notify_user` MCP tool when it needs a decision. You get a push titled with the agent and the project, with the agent's own text, and a desktop notification. It counts as "needs you", so it still arrives when that agent is on **Only when it needs you**; an agent on **Off** reaches only the desktop.

Dev commands: Settings > Notifications > **Notify me when a long command finishes**; each terminal keeps a bell icon to opt out, and a project can override the setting.

## Settings

- `notificationSound` (global, Settings > Notifications): sound when an agent finishes a turn.
- `needsInputSound` (global, Settings > Notifications): sound when an agent needs input.
- `sendNotificationsToPhone` (global, Settings > Mobile): mirror notifications to the paired phone.
- `mobilePushOverride` (owned by the phone): `inherit`, `always` or `never`; Always and Never win over the desktop checkbox.
- `agentPhoneNotifications` (global, Settings > Mobile > **Agent notifications on the phone**; project override in Project settings > Agents; per-agent pin from the agent's right-click menu or the phone): `all` (default), `needs-you` or `off`. Synced to your account, so every computer applies the same levels. Settable with `settings_set { key: "agentPhoneNotifications" }` at global, project or agent scope.
- `commandAlertOverrides` (project override, Project settings > Terminals): per-project command alert behaviour.

## Agent tools (MCP)

- `agents_report_status`: an agent reports where it stands, which feeds the statuses the notifications are built on.
- `notify_user`: the calling agent sends its own message (300 characters max) to your phone and as a desktop notification. One per agent per minute; the answer tells the agent when the phone was skipped (agent set to Off, phone notifications off, or you are at the computer).

## Providers

All providers, no difference: notifications derive from the session status, not from the CLI.

## Mobile

Push notifications on iOS and Android with the agent's avatar and name; tapping one opens the agent, and switches to the right desktop when the push came from another of your computers. The phone's Agents and terminals setting overrides the desktop's checkbox. Long-press an agent > **Phone notifications** sets that agent's level from the phone, with the same four choices as the desktop menu.

## Limits

- Desktop notifications follow the operating system's permissions: System Settings on macOS, System > Notifications on Windows, the desktop environment on Linux.
- Push works best with an AgentsRoom account (server delivery); without one a local Expo token is used when available.
- A session is marked unread only when it produces output while you are not looking at its terminal.
- Notifications tied to a project or the account (not to an agent) keep the app icon instead of an avatar.
- Several open windows (project windows, the detached terminals window) do not multiply the announcement: the banner, the sound and the push each go out once per event.
- Phone notification levels filter what the computer sends to the phone (agent pushes, and an agent on **Off** also leaves the iPhone Live Activity). Desktop banners, sounds and badges are not affected, nor are pushes sent by the server (cloud runs, chat, backlog replies).
- The computer sends the agent pushes: it must be running and connected, and the levels apply to the agents of that computer.

## Common questions

- **I am at my desk and still get pushes.** The phone is set to Always; switch it to Follow desktop.
- **No push at all.** Check Send notifications to phone on the desktop, the phone's Notifications permission, and that the phone is not set to Never.
- **Can I silence one project's command alerts?** Yes, in that project's settings, or with the bell on the terminal tab.
- **Can I get phone notifications from only one agent?** Yes. Set the project (Project settings > Agents) or the whole account (Settings > Mobile) to **Off**, then right-click the agent you want to hear from > **Phone notifications** > **All notifications**. On the phone: long-press the agent > **Phone notifications**.
- **My scheduled agent pings me every minute.** Set it to **Only when it needs you**: its finished turns stop reaching the phone, its questions and the messages it sends with `notify_user` still do. A trigger can also stop announcing each run: untick **Notify when it starts** in its editor.
- **Can a cron job or scheduled agent send me a specific notification?** Yes: an agent calls the `notify_user` MCP tool with its message, and it reaches your phone even when you are away from the computer.
- **Which agent finished?** The title of the notification, on the computer as on the phone, is the agent followed by the project, separated by a middle dot. An event that belongs to no project reads **AgentsRoom** instead.
- **I get the same message two or three times on my phone after a scheduled run.** That was one copy per open AgentsRoom window; fixed since 2026-09-10, an event is announced once.
- **My Android phone never gets a push.** Android builds did not include the Firebase (FCM) configuration, so the phone never obtained a push token, and the desktop also declared every paired phone to the server as an iPhone. Fixed on 2026-09-25: update the app, then open it once while paired so it registers again.

## Related

- [Agent Status Tracking](https://agentsroom.dev/docs/agent-status-tracking.md): the statuses behind the alerts.
- [Dynamic Island](https://agentsroom.dev/docs/dynamic-island.md): the always-on-top status window and its Done cards.
- [Needs Input Inbox](https://agentsroom.dev/docs/needs-input-inbox.md): the list of agents waiting for you.
- [Mobile-Desktop Sync](https://agentsroom.dev/docs/mobile-desktop-sync.md): pairing the phone.