The phone companion

Last updated 2026-09-29

The Weald iPhone app redeems a workspace invite on its own, which makes it the third redeeming client alongside the Mac and Android apps. It creates a device key for each workspace, keeps that workspace's group state in its own app container, and syncs over the relay. It has no git, so source code does not land in a workspace redeemed on the phone.

It can also pair to a Mac by scanning a QR code shown there, then talk to it directly over your local network with no relay, cloud, push service or account. That path gives a companion view of one Mac and does not join a workspace. What it can change is decided by switches on the Mac, all 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 instead of 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 has 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. The protocol has no keystroke path, so the type system enforces this and no setting can change it.
• 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 allows mirroring. Anything that writes needs the Mac's remote control switch on, this device granted the matching capability, and the project on an allowlist.

There is no approve verb, and moving a card to review or done stands in for one. Ticket text cannot be edited from the phone. The Mac enforces rate limits.

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, so they carry full content, including the project, the title and 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.