Agent Notifications

  • Desktop, mobile and web
  • All plans
View as MarkdownFeature page

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