Get Moshi
live

Live Activity

Surface agent events on the iOS lock screen and Dynamic Island while a session is running.

updated 3 weeks ago3 min readpage 29 / 40

When moshi-hook is paired and active on the host, agent events can start and update the iOS Live Activity and Dynamic Island so the latest status sits right on your lock screen — no app switch, no inbox dig. Moshi's server sends these updates through Apple's dedicated Live Activity push channel, separately from the normal notification used for banners and inbox delivery.

Answer from the lock screenA permission prompt answered from the lock screen, Dynamic Island, and Apple Watch — no unlock, no hunting for the session.

What you see

A running Live Activity shows:

  • The active session's title and the agent it belongs to.
  • The most recent event for that session — task complete, tool running, approval needed.
  • A tap target that takes you straight into the right place in Moshi.

The Dynamic Island variant keeps the same surface compact for the front of the phone.

Enable

Open Settings -> Hooks in Moshi and toggle:

  • Live Activity — turns the lock-screen / Dynamic Island surface on.
  • Open Inbox on tap — controls whether tapping the Live Activity opens the relevant inbox row or just brings the app forward.

Live Activities also require push notifications to be enabled in iOS Settings; the same screen surfaces a warning if iOS-level permission is missing.

What triggers an update

Live Activities track one session at a time. When no activity is running, the next non-ending agent event can use APNs push-to-start to create one even while Moshi is in the background. ActivityKit then gives Moshi an update token so later events update that activity in place.

A task_complete event updates the Live Activity with the completed state; it does not generate a separate iOS banner. When moshi-hook reports session_ended, the server sends the final state with an end event. That final state can remain on the lock screen for roughly ten minutes before iOS dismisses it. iOS may also reclaim an activity earlier, and you can stop it manually from the lock screen.

If an activity was dismissed, a later non-ending agent event can start a fresh one. Turning Live Activity off in Moshi unregisters push-to-start delivery so a new activity is not created remotely.

Approval and error events also trigger a visible push notification on top of the Live Activity, so they aren't lost if the screen is off. See Push notifications and webhooks for a complete request example and the difference between agent-event pushes and custom webhooks.

Host-resident integrations can override the automatic category lifecycle with liveActivity.action on POST /api/v1/hosts/:hostId/events: use upsert, end, or none. This directive controls only Live Activity delivery; normal push and eligible inbox persistence continue independently.

Demo

The Hooks settings screen includes a Test Live Activity button. Tapping it seeds a short-lived demo activity (and a small set of demo inbox rows) so you can see how the lock-screen surface looks without waiting for a real agent event. Clear the demo data from the same screen when you're done.

Troubleshooting

  • Live Activity never appears. Check that push notifications are enabled (Moshi shows a warning row when they aren't) and that moshi-hook serve is running on the host. See Hooks for setup.
  • Live Activity sticks after the session is done. The final session_ended state is intentionally allowed to linger for roughly ten minutes. Swipe the activity away if you want to dismiss it immediately.
  • Tapping does nothing. Make sure "Open Inbox on tap" is enabled if you expect a deep-link, and that the underlying inbox row hasn't already been cleared.