01 / SETUP

Pair in under a minute.

What you need

A Mac on macOS 13.5 or later, an iPhone on iOS 17 or later, and a Claude Code or Codex account. Provider usage and billing stay with your provider.

1. Install the Mac app

Open the Agent Remote DMG, drag the app to Applications, and open it. Use its Claude/Codex setup buttons if the command-line tools are missing or need sign-in.

2. Show a pairing code

In the Mac app, click Show pairing code. The QR code is single-use and expires after five minutes; treat it like a password while it is on screen.

3. Scan from the iPhone

In the iPhone app, choose Pair this iPhone → Scan QR code, confirm the Mac’s name, and tap Pair Mac. Your Mac appears in Chats whenever it is awake, online, and running Agent Remote.

4. Add a laptop

Install Agent Remote Client on the laptop. On your paired iPhone, open the gear menu, choose Add a device… → Send link, and AirDrop it to the laptop. The link opens in Agent Remote Client; click Pair Mac. No phone yet? Click Copy pairing link in the Mac app and send it to the laptop instead.

Optional

Enable Start at login on the Mac so remote access survives a restart. Enable Terminal Access to share sessions you start in Terminal with your phone.

02 / TROUBLESHOOTING

When something doesn’t connect.

“Mac unavailable”

The Mac must be awake, online, and running Agent Remote (the Agent Remote window on the Mac says Online). Sleep, a closed lid, or quitting the app all end remote access. Check System Settings → Energy to prevent sleep while plugged in.

Pairing code rejected

Codes expire after five minutes and work once. Click Show pairing code again for a fresh one.

Session won’t accept messages

A conversation owned by another client (for example a Claude session running in a separate terminal) is read-only until that client exits. Exit it, then resume from Agent Remote.

No reply notifications on the lock screen

Alerts appear while the app is open as soon as you turn notifications on. Lock-screen alerts are not yet available for every Mac; the Notifications screen says whether yours has them.

Camera or microphone not working

Check iPhone Settings → Agent Remote and allow Camera (pairing), Microphone and Speech Recognition (dictation).

Remove a phone

In Terminal on the Mac, run cd "/Applications/Agent Remote.app/Contents/Resources" && runtime/arm64/bin/node service/desktop/src/admin.mjs devices to list paired devices, then the same command with revoke DEVICE_ID in place of devices. On an Intel Mac, use runtime/x64.

03 / GOOD TO KNOW

A paired phone is a key to your Mac.

Sessions created from Agent Remote run with broad access on your Mac and without the usual agent approval prompts. Pair only devices you trust, keep your phone locked, and revoke a device you lose. See how your connection works and the privacy policy for what is and isn’t visible to the relay.