Companion for iPhone

Agents work for a long time and then stop, waiting on one word from you. Companion is the iPhone app that closes that loop: it pairs with your Mac, shows you every agent, and lets you answer without going back to your desk.

Nothing is relayed through a server. The phone talks to your Mac over an end-to-end-encrypted connection on your LAN or tailnet, and the feature is off until you turn it on.

Turn it on and pair#

1. On the Mac, open Settings → Companion and enable Mobile App.
2. Choose Pair a Device…. A QR code appears.
3. Scan it with the Agentastic app on your iPhone.

The Mac appears in the app, and the device appears in the Mac's Devices list.

The QR code carries the Mac's name, its reachable addresses, and its public key — never an access token. A payload that tries to smuggle one is rejected outright. If you're signed in to an Agentastic account on both devices, pairing uses that identity; otherwise the code carries a single-use invite so an accountless phone can still pair.

From a device's tile you can Revoke Access — it keeps the entry but cuts it off — or Remove it entirely, after which it has to pair again before it can connect.

dev companion drives the same flow from a terminal, which is handy on a headless or remote Mac.

What you can do from the phone#

Watch the fleet#

Every agent across every workspace, filtered by what it needs from you:

Filter	Shows
All Agents	Everything the Mac is running
Needs Attention	Agents blocked on a question or a permission request
Working	Agents currently running
In Review	Agents finished with changes waiting

Rows are sorted by urgency — errors first, then agents waiting on you, then review-ready, then running — so the top of the list is always the thing to look at.

Answer, steer, interrupt#

Open an agent to read its transcript. You can send a message, answer a question, respond to a permission request, or interrupt the current turn. It is the same live session the Mac is driving; there's no separate phone copy to reconcile.

A real terminal, not a screenshot of one#

Terminal output is rendered through an actual VT parser on the phone — cursor positioning, colors, redraws. A TUI agent that repaints its screen looks right, instead of degrading into thousands of lines of escape-code soup the way a plain text tail does.

Review the diff#

See what a worktree changed and read the file diffs, so "In Review" is something you can actually act on from a phone rather than a status you note for later.

Start a run#

The new-run sheet offers the same choices the Mac would: repository, base branch, agent, labels, and placement. Starting a run is the one action gated behind an explicit confirmation step on the phone.

What the phone deliberately cannot do#

Every method a paired device may call is listed in a single authorization table, grouped into three tiers — read, steer, and run. The Mac's request router denies anything not in that table, so a method nobody classified is refused by default rather than allowed by accident.

Destructive and exec-shaped operations are absent on purpose: removing a worktree, driving the browser, mutating scheduled tasks, packing a repository, importing a workspace. A stolen phone cannot delete your work.

Notifications that don't leak#

When an agent needs a permission, asks a question, finishes, errors, or posts a notification, the Mac forwards an encrypted push.

The payload is sealed with a per-device key derived at pairing time, and decrypted by the app's notification extension on arrival. The push relay and Apple's servers see only an opaque envelope addressed to a device id — never the agent's question, the repository name, or anything else.

Forwarding is strictly best-effort: a relay outage never blocks or slows an agent interaction on the Mac.

Catching up after being away#

The Mac keeps a durable journal of everything that happened, with monotonic sequence numbers from its database rather than an in-memory counter. When your phone wakes up, it asks for what it missed since its last cursor and gets exactly that — not a full resync.

The journal is scoped to the Mac's current launch, so if the app restarted, the phone can tell its cursor is meaningless and start clean rather than silently skipping or replaying events. Events are retained for seven days.

Connecting and reconnecting#

The app finds the paired Mac's current address on its own — LAN first, then a tailnet address if you run Tailscale — and copes with DHCP changes and Mac restarts. The connection pins the Mac's public key at pairing, so a device that answers on the right address but presents the wrong key is rejected.

Each connection negotiates fresh session keys; there is nothing long-lived on the wire to steal. Authentication must complete within ten seconds of connecting or the socket closes.

Related#

• Notifications — how the Mac decides an agent needs you
• Slack — the other way to answer an agent from your phone
• Remote Machines — agents that run somewhere other than your Mac