Agent Notifications

  • Desktop, mobile and web
  • All plans

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: Focus mode (Off / On / Scheduled), sounds and terminal command alerts.
  • Footer: the Settings gear (bottom right) opens a small menu with a Focus mode switch, on every screen. While Focus mode is on, a lit Focus on chip appears next to the gear as a reminder; click it to turn Focus mode off.
  • Projects home: the Focus button in the toolbar, and a bell next to each folder name (lit while that folder is silent).
  • Folder settings > Notifications, and Project settings > Agents: When notifications reach you (Inherit / Always / Focus mode / Quiet hours / Muted) and Let questions through.
  • Settings > Mobile: Send notifications to phone, Agent notifications on the phone (All / Summary / Needs you / Off), Project assistant (Same as agents / All / Summary / Needs you / Off) and Summary interval (5, 10, 15, 30 or 60 min).
  • Project settings > Agents: Agent notifications on the phone for that project's agents (Inherit / All / Summary / Needs you / Off).
  • Right-click an agent > Phone notifications: that one agent (Project default / All notifications / Summary every few minutes / Only when it needs you / Off).
  • Phone: Settings > Notifications (system permission) and Agents and terminals (Follow desktop / Always / Never); Agent notifications on the phone: the same three account rules as Settings > Mobile on the computer (all agents, project assistant, summary interval); 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), Summary (questions and messages right away, everything else grouped into one push every 5 to 60 minutes, 15 by default, with a "Still working" line for the agents still busy), 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 assistant rule (for agents with the Project assistant role only), 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. Typical set-up to hear only from the assistants: Agent notifications on the phone on Off (or Needs you) and Project assistant on All. 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.

Agents can also answer your quick questions with a fast reply (fast_reply): a short answer pushed to the phone even while you are at the computer, and shown in a bubble above the agent's input box. See Fast replies.

To keep a whole zone of work quiet (your personal projects while you are at the office), open the folder's settings > Notifications (gear or bell next to the folder name on the projects home) and pick when it may interrupt you: Always, Focus mode (silent while Focus mode is on), Quiet hours (silent on the days and hours you choose; an end earlier than the start runs overnight) or Muted. Sub-folders and projects inherit it, and a project can choose otherwise in Project settings > Agents. Then turn Focus mode on with the Focus button of the projects home, or set it to Scheduled in Settings > Notifications (for example Monday to Friday, 9:00 to 18:00). While a project is silent, its agents keep working and their state stays visible in the app: only the phone push, the desktop banner, the sound and the Dock bounce are held back. Let questions through still notifies you when one of its agents waits for your answer.

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), digest, 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, and from the phone's settings.
  • assistantPhoneNotifications (global, Settings > Mobile > Project assistant, or the phone): the level of the agents with the Project assistant role, above the project and account levels, below an agent's own pin. null (default) = same as the other agents. Synced to your account.
  • agentPhoneDigestMinutes (global, Settings > Mobile > Summary interval, or the phone): 5, 10, 15 (default), 30 or 60. Synced to your account.
  • focusMode (global, Settings > Notifications > Focus mode, or the Focus button of the projects home): off (default), on or schedule. Synced to your account. Settable with settings_set { key: "focusMode" }.
  • focusSchedule (global): hours of the scheduled Focus mode, { days: [0-6, 0 = Sunday], start: "HH:MM", end: "HH:MM" }. Synced to your account.
  • quietNotifications (folder settings > Notifications, or Project settings > Agents; folder and project scopes): always, focus, schedule or muted; absent = inherit the parent folder, then always. The project's own value wins over its folders.
  • quietSchedule (folder and project scopes): the quiet hours of the schedule mode, same shape as focusSchedule.
  • quietAllowQuestions (folder and project scopes): true lets an agent waiting for your answer notify you during the quiet period. Default off.
  • commandAlertOverrides (project override, Project settings > Terminals): per-project command alert behaviour.
  • leanSessionFile (global, Settings > Notifications > Lean session file, checkbox Only write the session file when something changes, default off, this computer only): agents launched afterwards stop rewriting their .agentsroom/sessions/<agent>.json file at the end of every turn. They write it on their first turn, then only when their title, type, Needs input, Waiting on an agent or status changes, and they skip the one-line summary of the turn. What you lose: that summary (agent row in the sidebar, Needs input inbox, text of the phone notification, voice mode fallback) and the Context Canary warning, which stands down because a quiet turn is no longer a miss. The tab title, Needs input, Waiting on an agent and the status pill keep working. Team run steps keep the per-turn file. Settable with settings_set { key: "leanSessionFile" }.

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 (project in its quiet period, 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 choices as the desktop menu. Settings > Agent notifications on the phone sets the account rules (all agents, project assistant, summary interval) from the phone; the computer applies them and syncs them to the account. Tapping a summary opens its agent, or the Activity tab when it covers several agents. Both need a desktop recent enough to send these rules: with an older one the card stays hidden and Summary is not offered. Settings > Focus mode on the phone switches Focus mode Off, On or Scheduled for the account (which folders go silent and the scheduled hours are chosen on the computer).

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).
  • Focus mode and quiet hours silence what the computer raises for a project (push, banner, sound, Dock bounce). Unread badges and statuses still update, and pushes sent by the server (cloud runs, chat, backlog replies) are not affected. Hours follow the clock of each computer.
  • The computer sends the agent pushes: it must be running and connected, and the levels apply to the agents of that computer.
  • A summary is sent only while you are away from the computer, like every other push: back at the desk, the held updates are dropped instead of buzzing the phone. Each computer of the account sends its own summary for its own agents.

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 I get one summary instead of a push for every agent? Yes: set the agents (or one project, or one agent) to Summary, and choose the Summary interval. Questions and notify_user messages still arrive at once.
  • Can I hear only from my project assistant? Yes: Agent notifications on the phone on Off and Project assistant on All, in Settings > Mobile on the computer or in the phone's settings. Use Needs you instead of Off to keep the other agents' questions.
  • 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.
  • Can I stop my personal projects from notifying me at work while their agents keep running? Yes: put them in a folder, set the folder's settings > Notifications to Focus mode, then turn Focus mode on (projects home toolbar) or schedule it in Settings > Notifications. Or give the folder its own Quiet hours.
  • Can I mute one project or one folder completely? Yes: Muted in its Notifications choice. Its agents keep working; tick Let questions through to still hear when one waits for you.
  • 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.
  • Can I stop my agents from writing to .agentsroom/sessions every turn? Yes: Settings > Notifications > Lean session file. Agents launched afterwards only write that file when their title or state changes (needs you, waits on another agent, status), not to refresh a summary line each turn. The tab title and the Needs input signal keep working; you lose the per-turn summary and the context drift warning. Restart a running agent for it to pick up the change. Asked for by DiamondQ, 2026-11-10.