Guides
Notifications
Mucq tells you when Claude needs you or is done, on the device you're at. Which one that is, and what it needs on the server.
On this page
Start Claude on something and walk away. When it needs you or is done, Mucq tells you: the Mac while you're at it, and your iPhone or iPad anywhere else, even locked.
When Mucq tells you
Two moments, and nothing else:
- Needs you: Claude asks a question, waits for you to approve a plan or a permission, or shows a form.
- Done: Claude finished its turn.
Nothing comes for Working or Idle, a crash, a lost connection or a session that ends. The project you're looking at doesn't notify on the device you're looking at it on.
The notification names the project and the server, webshop · devbox, and says Claude needs you or Claude is done. A session outside your projects shows its own name in place of the project's. A session your iPhone or iPad hasn't seen yet, one started after it last checked that server, says A session on one of your servers is waiting for you. or …has finished.
On the Mac, a click brings Mucq forward with the project selected. On iPhone and iPad, a tap opens that project's terminal. A newer notification for the same session replaces the older one.
Which device
The device you're at tells you, and the others stay quiet.
- At the Mac, meaning it's unlocked, its display is awake and you've used it in the last two minutes (ten while Mucq is in front), the Mac tells you and your iPhone stays quiet.
- Lock the Mac or walk away, and your iPhone or iPad tells you instead, even locked. The push leaves your server within about 15 seconds, and Apple delivers it from there.
- At an iPhone or iPad, meaning Mucq is in front and you've touched it in the last ten minutes, that device tells you, and no push goes out for the servers it checks.
- No Mac at all works the same way: start Claude on the iPhone, lock it, and it tells you.
- At no device, every iPhone and iPad with notifications on gets it.
At the Mac and the iPhone at once, both tell you. The Mac keeps the iPhone quiet only while its own notifications are on and allowed, and only for the servers it checks. Answering on one device doesn't clear the notification on the others.
Turning it on and off
Each device has one switch in Mucq's Settings, on by default: Notify me when Claude needs me or is done. There is nothing to set per project, per server or per event.
On iPhone and iPad, iOS asks for permission the first time a Claude terminal connects, or when you turn the switch on. Turn the switch off, and within seconds the device is unregistered from every server it's connected to.
On the Mac
The Mac tells you while Mucq is open. Closing its last window quits Mucq, and nothing of it stays running in the background. When Mucq starts again, it clears earlier notifications and doesn't report what happened while it was closed.
The Mac doesn't use push. Its notifications come from the states Mucq already reads over SSH, so nothing extra goes on the server for them.
What goes on the server
Notifications on iPhone and iPad start on your server: Claude's hooks call a small script, and the script asks Mucq's push relay to pass the notification on to Apple. Mucq sets this up over the device's own SSH connection, the first time it checks that server after it starts. There's nothing to do by hand.
- The script:
~/.local/share/mucq/notify. - One file per device in
~/.config/mucq/push/, and a random secret Mucq creates there.
The server needs curl, sha256sum or shasum, and outbound HTTPS. If one is missing, Mucq's Settings on the iPhone or iPad says so, for example: devbox can't send notifications: curl is missing.
When the last device is unregistered from a server (its switch turned off, notifications denied in iOS Settings, or the server deleted in Mucq), Mucq removes the script and the folder from it. You can also delete ~/.config/mucq/push/ yourself at any time.
The relay gets no names and no content. What it gets, and that it keeps none of it, is in the privacy policy.
Focus
On iPhone and iPad, Needs you is a time-sensitive notification, so it comes through a Focus that allows time-sensitive notifications. Done is an ordinary one and waits like the rest.
When none comes
- The server is offline, waits for a login, or can't reach the internet.
- Claude was started outside Mucq, so it has no hooks. Restart it from Mucq.
- The iPhone or iPad hasn't connected to that server since Mucq last started on it.
- The server is missing curl, sha256sum or shasum.
- On the Mac, Mucq isn't open.
A notification that fails isn't sent again, and Apple drops a push it can't deliver within 12 hours.