The short version
- Think of the relay as a walkie-talkie with a notebook. The walkie-talkie (a live socket) is instant when both ends have signal. The notebook (cloud documents) remembers everything, so nothing is lost when they do not.
- Your phone sends a prompt; your Mac runs it on your real files and streams the output back. The run is mirrored in the desktop app, so nothing happens off the record.
- The first versions sent whole snapshots and the phone's text could rewind mid-word. On 1 August the live mirror became an ordered, append-only event log.
- Luminair tells three kinds of offline apart (your phone, your Mac, your Mac's internet), and an outbox on the phone holds prompts until they can be delivered.
Tested from the couch.
Luminair is built inside Luminair, and a good part of that work is steered from a phone. That is how most relay bugs were found: a reply that stopped halfway, a prompt that ran twice, a Mac marked offline while it was clearly working. The sync code is full of dated notes about each one, and the fixes carry a Claude co-author line in git. The dates in this post come from those notes and commits.
Not a smaller terminal.
In March, Builder.io surveyed the ways to run Claude Code from a phone: SSH over a private network, companion apps, cloud containers, and Anthropic's own Remote Control, which shipped on 25 February 2026. The article is blunt about the oldest route: “SSH drops the moment your phone sleeps or hops from WiFi to cellular.”
Remote Control solved much of that. You scan a code and continue a local session from the Claude app. At launch it was a Max-only research preview; Anthropic's docs now list Pro, Max, Team and Enterprise, and promise that “if your laptop sleeps or your network drops, Claude Code reconnects automatically when your machine comes back online.”
Builder's own conclusion is the useful part: what people want from a phone is to check on long-running work and kick off new work. “These aren't terminal problems. These are orchestration problems.” We agree with the diagnosis. Our answer is different from theirs: keep the agent on your own Mac, next to your files, and make the link to the phone dependable.
A prompt's round trip.
You link the Luminair app on your phone to your Mac once, with a one-time code from the desktop settings. After that, a message you send from the phone makes this trip:
The phone writes it down
The prompt goes into a cloud inbox for your account. If the account room is connected, the same prompt is pushed down the socket at once, so the Mac does not have to wait for its next look.
The Mac picks it up
The Mac checks the inbox every five seconds as a fallback. Whichever path arrives first wins; the prompt runs once, on the Mac, with the session's engine and its real file tools.
The output streams back
Live output goes out over the socket and into the durable event log. The desktop mirrors the run in the same session, so when you sit down you can scroll through what happened.
“Done” must land
The final write is retried, up to four times, because it is the one that tells the phone the turn is over. A single lost “done” once left the phone waiting about 90 seconds, deciding the Mac had gone quiet, and queuing a finished turn again (2 August).
The account room is the newest layer. Since 6 September each signed-in account has one persistent socket, shared by the Mac and every phone. The Mac publishes on it everything the phone used to poll for, and receives prompts the instant they are sent. The code is explicit that the cloud documents “stay the durable record and the fallback when the socket is down”. The socket makes things fast; the documents make them safe.
From snapshots to a log.
The first live mirror was simple. As a turn streamed, the Mac rewrote one cloud document holding the whole reply so far, and the phone showed whatever it last read. That works until two writes cross in flight. The phone could receive an older snapshot after a newer one, and the text on screen would jump backwards, sometimes mid-word.
The rewrite, on 1 August, kept the snapshot for older phones but added an append-only event log beside it. Every live write now also records just the change since the last one, as an immutable document numbered in order. The phone reads the log incrementally and fills any gap before it moves on.
A fix the same day closed the other half. If a write to the log failed, the Mac used to announce that number anyway, so the phone moved past a document that did not exist and was left with a permanent hole. Now the log write is retried, and the push only goes out once the write is confirmed.
A research note written a few days later, before the next layer was added, looked back at three earlier relay generations and wrote down the rules they had paid for. Three of them explain most of what you have read so far:
- One writer per session stream: the Mac, so there is never a fight over numbering.
- Order by position, never by network arrival: that was the rewind bug.
- Push never leads the durable write: that was the hole bug.
Whose connection died?
“Offline” sounds like one state. On a relay it is at least three, and blaming the wrong device is its own bug. Luminair checks each one separately.
| What is down | How Luminair notices | What you see |
|---|---|---|
| Your phone | The phone cannot reach the cloud at all, or the system reports no network. | The phone says it is the one offline, instead of blaming the Mac. New prompts wait in the outbox. |
| Your Mac | The Mac's presence stamp stops changing. The phone judges this by its own clock: no change for 25 seconds means offline. One missed check is forgiven. | The Mac shows as offline on the phone. |
| Your Mac's internet | The Mac's five-second inbox check is also its heartbeat to the internet. A streak of network failures there marks the Mac as offline since the first one. | “This Mac has had no internet since 14:02. Codex could not reach its server. Reconnect and send again.” |
The second row hides a subtle fix. The phone used to compare the Mac's clock with its own. A few seconds of clock drift made the status flicker, and more than 15 seconds of drift showed a live Mac as permanently offline. Now the phone only asks whether the stamp has changed recently by its own clock, which clock drift cannot fool.
The third row came from a bad afternoon on 17 September. For 18 minutes the Mac had no internet. Claude said there was no response from the API, Codex timed out, Antigravity streamed nothing, and Google's client said it was not logged in. Five messages, one cause, and none of them said “offline”. Now, when the app's own connection checks are failing, the error says so. A usage limit or a broken sign-in is still reported as itself, because those are not the network.
Write now, send later.
The last piece lives on the phone. Since 23 July, anything you queue on the phone is written to the phone's own storage first, marked as not yet confirmed, and only then sent to the cloud queue your Mac drains. The storage survives the app being closed and airplane mode.
When the connection returns, the phone flushes every session with unsent items, and it also retries every 15 seconds while the app is open. It never simply overwrites the cloud queue. It pulls the current queue, merges its own items in, and pushes the result, so a batch written in a tunnel cannot wipe out items the Mac already ran while you were away.
Two small ledgers make that safe. One remembers, for seven days, the ids of items the phone already ran, so a Mac that wakes up hours later and mirrors a stale copy back cannot make an old request run twice. The other remembers deletions for a day, so something you removed offline does not come back when you reconnect.
Link a phone in a minute.
- 1On the Mac, open Settings › Mobile relay. Under Pair a phone, create a code. It works once and expires after 10 minutes.
- 2Type the code into the Luminair app on your phone. The phone appears under Connected devices, where you can unlink it later.
- 3Under This computer, keep Accept work from other devices on. Turn on Protected Mode for turns from other devices if you want relayed turns kept inside the session's folder, so a lost phone cannot reach the rest of the Mac.
The Mobile relay page is part of the Pro+ plan.
What the relay can't do.
Worth knowing
- Your Mac has to be on, awake and running Luminair. The phone is a remote for your Mac, not a cloud machine. A Wake from phone option can reopen Luminair after a crash, but it cannot power on a Mac that is off.
- The outbox can only deliver once both the phone and the cloud are reachable, and the Mac only runs it once it is back.
- A socket is fast but fragile; when it drops, the five-second inbox check takes over, so replies feel slower until it reconnects.
- We have not published delivery-time measurements for the relay.
Sources
- Builder.io · 2 March 2026Claude Code on your phone
- Claude Code docsContinue local sessions from any device with Remote Control
Steer your Mac from anywhere
Link your phone once, and keep your agents moving from the couch, the train or the queue for coffee.