Reins

Claude Code notifications on your phone

A long task runs and you leave the desk. What you want to know is when Claude Code needs you, when it finished, and when it got stuck. This guide covers what Reins tells your phone, and what it takes for that to reach you with the app closed.

What the phone hears about

reins setup installs a set of Claude Code hooks, and only one of them blocks. The others run in the background and keep the phone’s picture of each session current:

  • Notification: Claude Code is waiting on you, so the session shows under Needs you.
  • Stop: the turn finished, so the session reads as idle.
  • StopFailure: a turn that died is not mistaken for a quiet one.
  • PostToolUseFailure: an agent failing the same tool over and over is visible.
  • PermissionDenied: a blocked agent says so, even where nobody can be asked.

The Inbox lists what needs you first, with the machine named, and a count of sessions still running. Codex, which cannot be asked for approval, still reports its finished turns the same way.

With the app open or in the background

An approval or a finished turn raises a notification on the phone. On Android the notification is marked private, so a secure lock screen hides its body. With the Reins app lock on (Face ID, a fingerprint or the passcode, from Machine, then This phone), the notification and the iPhone Live Activity leave the raw command off the lock screen altogether.

With the app closed

A phone in a pocket is not connected: the OS suspends the app within seconds. With no phone attached, the daemon lets approvals through to your desk prompt at once, which is fail-open doing its job. Two optional things close that gap.

The wake-up push, on Android

With alerts on, when an agent asks and no phone is attached, the daemon sends one notification that says only “An agent needs you” and holds the approval for up to 45 seconds while the phone reconnects. The push carries nothing about the command; the approval itself still travels over your paired connection. A phone that does not come back costs one hold, and approvals then pass straight to the desk prompt for ten minutes.

The push goes through the Reins relay by default, which stores nothing and never sees what the agent asked, or through a Firebase project you own. Staying reachable has both.

Stay connected, on Android

Machine, then This phone, then Stay connected. A foreground service holds the link open in the background, so there is no push and no hold; the request simply arrives. The cost is a permanent quiet notification.

On iPhone today

Alerts arrive while the app is open or backgrounded, and a pending approval shows on the lock screen as a Live Activity. There is no closed-app push on iPhone yet, because that needs Apple’s push service; until then a request that arrives with the app closed goes to the desk prompt after three minutes, as it always did.

Test it without waiting for an agent

reins push list
reins push test

list shows each phone registered for push and whether it is reached through the relay or your own project. test sends the wake notification now.

Next