The phone companion
Last updated
The Weald iPhone app is a companion to a Mac, not a second client. It pairs by scanning a QR code shown on that Mac, then talks to it directly over your local network: no relay, no cloud, no push service and no account. What it can change is decided by three switches on the Mac, and all three are closed by default.
Pairing
The Mac shows a single-use code carrying a contract version, the service name to look for, its public key and a sixty second secret. The phone scans it, generates its own keypair, and both sides derive a shared key from the exchange salted with that secret.
After that, the phone finds the Mac by Bonjour service discovery for _weald._tcp rather than by a typed address, and holds one connection to it. Every frame is sealed, carries a replay counter, and is refused outside a two minute clock skew.
The phone's key lives in the iOS keychain, available only when the device is unlocked and never synced off it. Unpairing deletes it along with the cached snapshot, the queued commands and the alert history.
What it shows
The shell is four places: Home, DMs, Activity and You, with a workspace rail down the side and one tile per shared project.
- Needs you is the attention queue: what a person has to answer, with acknowledge and dismiss.
- Sessions are the Mac's live agent sessions as channels, with a transcript that streams while you are looking at it and quick replies when a session is waiting on an answer.
- Board is the Mac's kanban on a phone, same columns in the same order, with a card detail sheet that subscribes to live status while it is open.
- Terminal is a read-only stream. There is no keystroke path in the protocol at all, so this is enforced by the type system and not by a setting.
- Usage draws the Claude five-hour and weekly windows as arcs with their reset times.
- Projects shows per-project git and team rollups: names and counts, never paths, diffs or commit bodies, because none of those are on the wire.
What it can change
Pairing alone buys mirroring. Anything that writes needs the Mac's remote control switch on, this device granted the matching capability, and the project on an allowlist.
| Capability | Allows |
|---|---|
| none | Viewing, plus acknowledging and dismissing attention items |
| chat | Starting a session with a first prompt, and sending follow-ups |
| terminal | Watching a session's terminal output, read only |
| board | Card verbs: claim, review, done, block, stop an agent, and hand a card to an agent |
Moving a card to review or done is the closest thing to an approval; there is no separate approve verb. Ticket text cannot be edited from the phone. The Mac enforces rate limits, not the phone.
Offline
Prompts and card verbs issued while the Mac is unreachable are queued, expire after twenty minutes, and replay when the connection comes back. A snapshot older than five minutes is labelled on screen with its age.
Notifications
Local, raised by the phone itself the moment it accepts a snapshot. There is no push service, no device token and no server that could see them, which is why they carry full content: the project, the title, the question an agent asked.
The cost is stated in the app's own settings. Away from your network the phone learns nothing, and in the background iOS decides how often it gets a chance to check.
Alert settings cover per-class switches, per-project mutes, quiet hours and a history of what fired.
Before you have a Mac
There is a built-in sample workspace, generated on the device, so every screen works with nothing paired. It is labelled as a sample wherever it appears.
Requirements
iOS 17 or later. The app asks for local network access, which is how it finds the Mac, and for the camera, which is how it reads the pairing code. Notification permission is requested when you turn alerts on rather than at launch.