Agent Notifications

pocketty tells you when an agent in herdr needs you, or when it finishes. Notifications are optional. Without them, the App only talks to your own hosts.

What You Need

• The daemon running on the host.
• herdr on the host, with your agents in its Panes.
• Notifications allowed for pocketty on the phone.
• The host can reach relay.pocketty.app over HTTPS. The daemon sends each sealed alert there.

Turn Them On

1. Open pocketty, and allow notifications when iOS asks. If you said no before, turn on Push Notifications in Settings → Notifications in pocketty. It opens iOS Settings → pocketty → Notifications, where you allow them.
2. Connect to the host once. pocketty pairs with the daemon by itself, over SSH.
3. On the host, run pocketty devices. It lists your phone when pairing worked.

If your phone is not in the list, the App could not find pocketty on that host, on the PATH of a login shell or in ~/.local/bin. See Install the Daemon.

pocketty pairs again by itself when something changes, for example after iOS gives the App a new push token.

When You Get One

Agent goes	Notification
to blocked	claude is blocked, every time it starts to wait for you
from working to done	claude is done

The daemon waits 2 seconds before it sends, and sends only the last state. So an agent that flips back and forth makes no noise. A newer notification for a Pane replaces the older one.

For a finished agent, pocketty does what herdr does. If herdr shows the agent’s tab in a terminal that has focus, herdr does not chime, and your phone gets no notification. This includes the 2 seconds that the daemon waits. If no herdr client is open, an agent in herdr’s last active tab also sends no done notification.

Each notification reads like this:

• Title: the agent and its state, for example claude is blocked.
• Body: the host, the workspace and the tab, for example studio · pocketty · relay.

iOS groups the notifications of one workspace together.

Answer an Agent

Tap a notification. pocketty connects to the host, opens that exact Pane, and takes control of it. Answer in the terminal: type your reply, or use Enter, Esc and the arrow keys above the keyboard. See Keys and Text.

You cannot answer from the lock screen. Each agent asks in its own way, and the right key differs, so pocketty does not guess.

If the Pane is already on screen when the notification arrives, pocketty hides it. You are looking at it already.

What a Notification Contains

Only the agent’s name, its state, the host, workspace and tab names, and the time. Never text from the terminal.

The daemon seals it for your phone before it leaves the computer. The relay and Apple see only ciphertext. If a seal cannot be opened, the phone shows the placeholder pocketty: Agent update. See Sealed Notifications.

Test It

1. Start an agent in a herdr Pane on the host, and give it a task that asks for approval.
2. Lock the phone.
3. When the agent stops to ask, a notification arrives within a few seconds.

Turn Them Off

• For every host: turn off Push Notifications in Settings → Notifications in pocketty. pocketty tells each host to stop sending to this phone. A host that pocketty cannot reach now gets the message the next time you connect to it. Each host keeps your phone paired, so when you turn notifications on again, they start again at once.
• Turning off notifications for pocketty in iOS Settings does the same.
• For one host: on that host, run pocketty devices to find your phone, then pocketty unpair <id>. See Remove a Phone.

If Nothing Arrives

See Troubleshooting.