iPhone Notifications

Your iPhone or iPad can tell you the moment a session needs you, even if you’re not looking at your Mac. There are three delivery paths depending on what’s running and where, plus a notification inbox that keeps every event — interrupting or not — and one set of toggles that gates which events actually interrupt you.

The notification inbox: shared with the Mac

Behind the bell icon in the companion app sits the same notification inbox described on Notifications & the Menu Bar: every notification-worthy event — permission needed, done and waiting, a question, a plan ready, a failed session, a cleanly-ended session, media the agent showed you, and deliberate notify_user messages — lands there, whether or not it also interrupted you as a banner or push. Notify messages can show Important or Urgent and include attachment chips.

• The app icon carries an unread count badge, alongside the bell’s own in-app badge. Only entries that actually notified you count; a card that stays in the bell without interrupting you never raises that number.
• When the current session list resolves an inbox entry to a project lead on its source Mac, the card title uses Project lead followed by the project name; otherwise the stored title remains.
• Read state is one shared truth across the Mac and every paired device. Open an entry (or mark it read) on your phone or tablet, and the Mac shows it as read too — and the other way around. There’s no separate “read on this device only” state to track.
• Viewing a session reads its cards, too. Open a session and keep looking — after about a second with the app in the foreground, that session’s unread bell cards clear on their own, the same rule as on the Mac. Leaving the session or backgrounding the app before that second is up leaves them unread; a different session’s cards are never touched.
• Tapping a session notification or bell card switches to that session’s Code or Cowork mode before opening the session or its project lead chat.
• A session that exited cleanly and an agent showing you media are inbox-only by default. A scheduled job stays quiet when it finishes, sits idle, or exits cleanly. Permission, a question, plan approval, and a session failure from that job notify you like any other session. A deliberate notify_user call is the opposite among status-reason switches: permission/finished/question/plan/failed never mute it, even from an automation. The master Push switch and Hide names in push still apply. Attachments can be downloaded from a compatible Mac connection. Every other kind below still follows the interrupt path described next — subject to the reason toggles.

Local notifications on status change

When the companion app is open and connected to your Mac, it watches the session list itself. Any session that transitions into an interrupt-class waiting state — needs permission, is done and waiting, has a question, or has a plan ready — posts an iOS notification with the session title (or Project lead followed by the project name for a project lead) and a status line as the body, on top of the inbox entry that comes with it. A session that failed with an error lands in the bell only, like the other system notices, unless Show system notices as banners is on.

Your Mac decides what counts as an event before anything reaches your phone. In particular, a session that reports itself finished while its own child sessions are still working isn’t forwarded at all — see When a session counts as finished. Permission and plan cards from roles or child sessions always reach you; questions reach you whenever the lead is not allowed to answer them.

When the Mac isn’t driving notifications centrally — it hasn’t announced that capability, or the connection has dropped — the phone decides locally, by the same role rules. It reads the role from the session list the Mac sends: a project lead’s finished session, or one led by a live project lead, doesn’t interrupt you; a question, a permission, or a plan still does. Against an older Mac that doesn’t announce those role marks, the role stays unknown, so a finished session stays silent while questions, permissions and plans keep coming.

A session that has simply exited cleanly still creates an inbox entry the moment it happens, but no longer posts this local notification — check the bell instead of expecting a banner for it.

A few rules keep the interrupting notifications from being noisy:

• It only fires on a genuine transition into waiting, not on a change of reason while already waiting (a session moving from “has a question” to “needs permission” doesn’t re-alert).
• Codex can ask a question and keep working. Your Mac reports the new question once, immediately, with its question text; the session shows “Question pending” and stays 🟢. Longer output pauses or an open asynchronous question editor also trigger no repeated notifications. Only when the turn ends with the question open does exactly one additional 🟡 notification follow. Real blocking questions and approvals are independent of this.
• A session that hits a usage limit is not “done”: it shows ⏳ in the list, and your Mac never sends a “done” notification or push for it — also not to an older device that doesn’t know the limited status yet and displays it as done. See Usage Limits & Auto-Continue.
• The session you currently have open (attached) never posts a banner for itself — you’re already looking at it.
• Tapping the banner (or its “Open” action) brings the app forward and jumps straight to that session’s detail screen.

There’s no “done” action to acknowledge a notification from the banner — that would imply a round trip to the Mac, and there isn’t one for a plain dismiss. The only action is opening the session; from the inbox, you can also just mark it read without opening anything.

Note

This path needs notification permission, requested once during pairing.

Grouping

Local notifications are grouped by kind and project: a project’s permission requests, its questions, its board items, and its finished sessions each gather under their own thread in Notification Center, while media and agent messages share one global group and failures and other system notices another. On a Mac-driven banner the project name is also carried as the summary argument, so a collapsed group names the project it belongs to.

Mac-driven text when the Mac is online (localized, name privacy)

If your Mac is online and reachable, it takes over building the notification text instead of letting the phone guess from a status diff. This kicks in as soon as the Mac announces the capability for it — before the first status change, so there’s no race where both sides post a banner for the same event.

What changes in practice: the text is now the Mac’s own wording, already localized to your Mac’s UI language, and it respects the Mac-side privacy setting. If you’ve told the Mac to hide names in notifications, the device shows a generic, nameless sentence with no project subtitle instead of “Project X has a question.”

Everything else about the banner (tap-to-open, suppressed for the open session) works the same. See Notifications & the Menu Bar for the Mac-side controls that drive this text.

Push when the app is closed/offline (APNs)

If the companion app isn’t running, or your device has dropped off the relay connection, the same waiting-events arrive as a real Apple push notification instead — banner or lock screen, same as any other app. Tapping it launches the app and opens the session directly.

Push only fires when your device is genuinely offline at the moment the Mac sends the event — an actively connected device gets the local/Mac-driven banner instead, never both. It’s rate-limited to one push per device every 30 seconds, and pushes for the same account collapse into the latest one rather than stacking up. A brief relay reconnect does not alert again for the same card that remained open; a newly replaced card can alert once.

The APNs token is registered automatically right after pairing — there’s nothing to turn on separately.

Not only waiting statuses reach your phone. A board question, a permission or plan approval, a deletion request, a deletion-watchdog pause and a signed-out account also arrive as a push on your iPhone. Tapping one opens its target — the board item, the workflow decision, or the matching inbox entry — as soon as the mirrored bell on the phone knows it; if the mirror hasn’t delivered that entry yet, the tap waits up to five seconds for it before falling back to opening the session. The notification itself carries no new field: it rides on the entry ID the Mac already has. A board notification opens the board in the project’s mode and tab, then scrolls to and briefly highlights the item; a done or missing item shows the same short notice. See Opening an item from a notification.

Offline push texts come from the server, not the Mac: Apple only ever sees a fixed, nameless English sentence per occasion (privacy by design — see Notifications & privacy). One of those occasions is “usage limit over without the agent resuming on its own”, which since September 2026 carries its own honest sentence (“A session’s usage limit is over”) instead of the generic “A session has finished”. This wording requires a current server and Mac; with an older server the same event keeps arriving with the previous “finished” wording.

Usage brake messages

When an account reaches its own usage limit and the usage brake holds automation, exactly one notification per account episode goes to the top session: Usage brake: <account> is holding automation. It lands in the inbox and, by the usual rules above, as a Mac banner and an iPhone push — with no session name when Hide names in push is on. After the release comes Usage brake released: <account>, with N held deliveries caught up when something was actually caught up; deliveries made with Deliver once do not count.

Workflow decisions arrive as a push — you decide inside the session

When a workflow run reaches your approval or halts (rounds used up, budget used up, or a stage you rejected without a loop), the Mac creates one inbox entry per decision point and sends it as a regular agent notification: a banner on the Mac, and a push to the phone. The push carries no lock-screen actions — there is nothing to approve from the notification itself. Tap it: the session opens, and once the phone is attached the Mac sends the current decision snapshot, which appears as the workflow decision card in the command zone (how the card works). The name-privacy setting applies as usual: with hide names in push on, only the generic text (“A workflow run needs your decision.”) leaves the Mac, and with push off the entry stays in the inbox without a push.

Deletion requests and the deletion watchdog

A critical deletion request arrives as its own inbox kind deletionRequest, in the Action required group. The deletion watchdog pause arrives as deleteWatchdog, also Action required, and now also sends an iPhone notification (it used to stay on the Mac). Tapping the push opens the oldest open decision of that kind. Against a current Mac the inbox shows Open decisions with Allow / Deny or Resume / Stop agents; against an older Mac the row stays text without buttons.

Job-change approvals keep the existing kind jobApproval. You still approve them from the phone when the Mac announces that capability — see Scheduled Jobs.

Account sign-out alerts

When vord on your Mac sees a Kimi, Grok, or Muse account move from a known signed-in state to one that needs sign-in again, it creates one accountSignedOut inbox entry for that account and sends a phone push. The first observation after launching vord does not alert because there is no known previous state. Signing in again on the Mac clears the state, so a later sign-out can alert again. The entry is Action required; it is account-wide and does not repeat for each session. Hide names in push sends a generic account message instead, and turning off push keeps the inbox entry without a push.

External start requests arrive as a push — you decide on the phone

When an external AI app asks to start a session on your Mac (external MCP), the request also reaches your phone as a push with two lock-screen actions: Review opens the approval sheet (client, project, agent, model, title, full prompt, time remaining, Reject/Start), and Reject declines on the spot. A session the Mac started automatically pushes with a Stop action instead. The same request sits in the inbox with a Review button; against an older Mac it shows “Approve on Mac” and you decide on the Mac. Only your own paired device can decide, and one decision counts — a request someone already settled answers “This request was already decided.”

The five reason toggles: gate the interruption, not the inbox

Every notification path — local diff and push alike — is gated by the same five switches, all on by default:

Toggle	Fires when a session…
Needs permission	needs a permission decision
Done and waiting	has finished and is waiting for you
Has a question	is asking a question (AskUserQuestion)
Plan approval	has a plan ready to approve
Session failed	has crashed or exited with an error on its own — never fires for a session you ended yourself

Turn any of them off in Settings → General → Notifications (the gear icon opens the settings sheet from either tab) and you stop being interrupted for that reason on both local and push delivery — there’s no separate switch for one channel only. The event still shows up in the inbox either way; these toggles only decide whether it also demands a live glance.

The settings sheet’s Notifications section lists Session failed (“Session fehlgeschlagen” in German) alongside the other reason switches — turn it off and a crashed session still lands in the bell, without interrupting you.

Action items without their own reason switch — deletion requests, deletion-watchdog pauses, external start requests, and account sign-outs — are always delivered and cannot be switched off. A reason switch only controls the notification types listed above that have their own switch.

With a current Mac that announces the settings channel, the phone can also change these switches instead of only obeying them: Settings → Mac settings → Mac notifications carries Push to this iPhone, Include child sessions, Also notify when sessions started by the project lead finish, Notify about every finish, Show system notices as banners, Mute while at the Mac, and the reason toggles — the five above plus Board activity. Every change runs through the Mac’s own setter, so it applies on the Mac immediately, and the Mac pushes the new state back to every connected device. The one exception is Hide names in iPhone notifications — that privacy switch stays on the Mac. Against an older Mac the section does not appear. Details: Changing Mac settings from the phone.

A session ending cleanly and an agent showing you media have no toggle here at all — they’re inbox-only by design (see above), not a seventh and eighth switch waiting to be added.

Device-aware routing (no double alerts)

If your Mac and your iPhone or iPad are both around, you don’t get alerted twice. The device that’s actually active — Mac open in front of you, or the companion app in the foreground — stays quiet; the other one’s channel carries the alert. If neither device is active, both alert, so nothing gets lost.

This runs on a presence signal the app sends whenever it is foregrounded and a session is open — it doesn’t have any UI of its own on the device side; it just decides, silently, whether a given banner or push actually gets shown. An older app build that doesn’t send this signal simply never counts as “active,” so the Mac falls back to its own presence logic and behaves as if no device were paired.

The Mac-side opt-out for this (“don’t push to my iPhone while I’m at the Mac”) lives in the Mac’s own notification settings — see Notifications & the Menu Bar for that toggle. With a current Mac, the phone’s Mute while at the Mac row flips that same switch.

Note

Pro-only. Companion notifications require an active Pro subscription and a paired iPhone or iPad — there’s no companion notification path on Basic. For what the relay does and doesn’t see about these events, see Privacy & Data.

When a Mac has no active license

If vord on the Mac loses its Pro plan, it sends one final notice before disconnecting. The iPhone shows Remote is paused: vord on this Mac has no active Pro plan. in place of an empty session list and in that Mac’s offline banner. The notice is remembered for that Mac across app restarts and clears when the Mac sends a normal list again.