Push Notifications

A paired phone can alert you when a session needs you. Notifications are the reason the companion app is worth having: an agent that stops for a permission prompt at 11pm is only useful to know about if something tells you.

The five categories

Category	Notification title	Channel	Fires when
input-required	Agent needs your input	Needs attention	The agent stopped and is waiting on you, including permission prompts
turn-complete	Turn complete	Completions	The agent went quiet and stayed quiet. Since v0.36.0 this waits for the session to settle rather than firing on every pause, because a conversational back-and-forth leaves gaps of tens of seconds and each one used to be its own notification
plan-complete	Plan complete	Completions	The agent finished planning
session-failed	Session stopped	Failures	The session exited with an error
spawn-stalled	Still preparing	Stalls	A spawn is taking too long waiting on its git worktree

Each category maps to its own notification channel, so you can tune them independently in your phone’s system settings. Muting completions while leaving “needs attention” loud is the common setup.

Permissions

The app asks for notification permission at runtime rather than on first launch, so the request arrives when it makes sense. Declining leaves the rest of the app fully usable; you simply have to open it to see what changed. Unpairing a device clears its push registration.

What the delivery network sees

Push notifications travel through Expo’s push service and then the platform networks, which are Firebase Cloud Messaging on Android and APNs on iOS. That path is outside the encrypted tunnel your phone and desktop share, so Kangentic does not put anything meaningful in it.

The relay is not on this path at all. It forwards a live connection between two devices and has nowhere to hold a message for a phone that is not connected, which is exactly why the offline case is a push notification rather than something queued for later.

Every push carries the real content as an encrypted blob. What travels alongside it differs by platform, and since v0.36.0 the two are deliberately different:

• Android gets a data-only message: no title, no body, no channel id. Android renders an incoming notification payload itself before handing off to the app, so anything visible in the push was drawn a second time on top of the decrypted notification the app posts. Sending nothing visible is what stops the double render, and the channel is chosen on the device from the decrypted category anyway, which only the phone can know.
• iOS keeps a generic title, Kangentic, and a static placeholder body for the category. With no notification service extension yet, that placeholder is the only visible content an iOS push can have, so stripping it would turn iOS from silent-because-unauthorized into silent by construction.

The blob is sealed with XChaCha20-Poly1305 under a key your device generated, and it is opened on your device. Expo, Google, and Apple see at most the placeholder, your device’s push token, and the delivery timing. They never see the task name, the agent output, or anything else from the session.

If a payload cannot be decrypted for any reason, the app shows the generic placeholder rather than ciphertext or a partial result.

Local notifications

When the app is running in the background with a live connection, it can raise the same categories directly from the activity it is already watching, without a round trip through the push network. The titles and channels are shared with the push path so the two cannot drift apart.

Next steps

See also:

• Install Kangentic Mobile - get the app on iOS or Android
• Security & Encryption - how the tunnel and the push envelope are protected
• The Hosted Relay - why nothing waits for an offline phone
• Privacy Policy - what leaves your device and what does not
• Notifications - the desktop app’s own alerts