There are five ways people try to run Claude Code from a phone. Four of them require a server, custom daemon, or paid tunnel. One uses iMessage as the interface. This is a practical guide to that fifth path.
The five options (and why most of them break)
- SSH into your Mac from a terminal app. Works if you have Tailscale, Mosh, or a VPN. Brittle. Mobile keyboards make Claude Code prompts painful.
- Anthropic's web interface. No native iOS app. Safari works but you lose Claude Code's local file context. Different product.
- Anthropic's iMessage plugin. Real, free. Text-only. No voice in, no voice out, no file routing.
- Cursor / Aider / other Claude wrappers. Most are desktop-only. Even the ones with mobile companions don't have voice.
- iMessage as the interface, with a small bridge on the Mac. What we built. The rest of this guide.
What "iMessage as interface" actually means
You text or voice-message a dedicated iCloud account from your iPhone. A small script on your Mac watches for those messages, pipes them into Claude Code, and texts the responses back, iCloud Drive handles any file syncing both ways.
The phone side is just Messages. No new app to install, no login, no notifications setup. The Mac side is one bash script + one AppleScript helper + (optional) three iOS Shortcuts for the voice layer.
The five components
1. A dedicated agent iCloud account
Free to create at appleid.apple.com. The point is to keep your real iMessage (banking, family, 2FA codes) separate from the agent. The bridge only listens for messages addressed to the agent address.
2. The bridge script (Mac → polls chat.db)
Apple stores all iMessage history in ~/Library/Messages/chat.db (SQLite). A small bash + sqlite3 polling loop checks every 3 seconds for new incoming messages addressed to the agent account, deduplicates them, and writes each new message to a JSONL stream file your Claude Code session can read.
Total bridge: ~80 lines of bash. The interesting parts: Apple's Cocoa epoch starts at 2001-01-01 and stores message dates in nanoseconds, you have to convert if you want to filter by time. And Terminal needs Full Disk Access granted (System Settings → Privacy & Security → Full Disk Access → +Terminal) or sqlite3 can't open chat.db.
3. The send script (Mac → Messages.app via AppleScript)
AppleScript talks to Messages.app over the iMessage service. A wrapper script takes a target handle and a message text, generates the AppleScript dynamically, and shells it out via osascript. Once Terminal has Automation permission for Messages (granted on first prompt), this Just Works.
4, iOS Shortcuts (the voice layer, optional but the magic)
Three Shortcuts on iPhone:
- Text My Agent. Siri triggers it ("hey Siri text my agent"), it dictates, sends as iMessage, optionally reads any reply aloud.
- Read My Agent, runs as a Personal Automation when a message from the agent arrives. Uses iOS's built-in Speak Text action to read the reply through your AirPods (or speaker).
- Text My Agent (silent), same as the first but without the readback. For meetings, cinemas, etc.
These are all installable from a single iCloud Shortcut share link in 2 taps each.
5, iCloud Drive (the file layer)
Drop a file into a shared folder on your phone, it's on the Mac a second later. Claude Code can read or modify files in that folder, and the changes sync back to your phone. This is Apple's existing iCloud sync, no new infrastructure needed.
What this gets you
From your iPhone (anywhere, gym, car, coffee shop, casino floor, walking the dog):
- Text a question to Claude, get a reply in 2-5 seconds.
- Voice-message a question. Claude reads it as text (with whisper.cpp, transcription is local + private).
- Send a screenshot of an error. Claude sees the image (via the bridge passing the attachment path to Claude Code).
- Drop a log file in iCloud Drive. Claude reads it on the Mac.
- Tell Claude to ship, it commits, pushes, deploys, and texts you back when it's live.
What it doesn't require
- No API keys. Claude Code already has its own auth on the Mac. No new keys.
- No third-party server. Apple's iMessage is the only outbound service. No SaaS dependency that could fold or change pricing.
- No tunnel or VPN. No Tailscale, no ngrok, no Cloudflare Tunnel, iMessage works through whatever WiFi or cellular you're on.
- No new mobile app. Just Messages and Shortcuts (both stock iOS).
What it does require
- An iPhone (8 or newer, iOS 15+) with the Shortcuts app.
- A Mac (mini, MacBook, or Studio) on macOS 12 or later, kept on while you're away.
- Claude Code already installed and working on your Mac.
- Both devices on the same Apple ID (so iMessage routes between them).
The fastest install path
Three options, ranked by time-to-working:
- Use Remote Claude. $49 PDF setup guide + the 3 pre-built Shortcuts (free bonus). Setup in under an hour. linkpayhub.com/remote-claude.html.
- Build it yourself from scratch, possible. The architecture in this post is the whole story. Allow 4-6 hours for the first build, longer if you hit the macOS Automation permission gotchas (the bridge needs Full Disk Access, Messages.app needs Automation permission, Shortcut imports may need "Allow Untrusted Shortcuts" enabled).
- Wait for Anthropic. Voice mode has been "rolling out" for months at ~5% of accounts, iMessage plugin is text-only. Indie shipping cycle vs. Anthropic shipping cycle is wildly different.
The honest tradeoffs
This setup isn't for everyone:
- You need a Mac always on. If you don't already have one running, this isn't free, you need a $599 Mac mini at minimum.
- iOS only. Android can't use iMessage. (You can adapt the same loop with SMS-via-API or Telegram, but that breaks "no third-party.")
- iMessage outages = your Claude is offline. Apple has them rarely (a few times a year) but it happens.
- Your Mac running Claude unattended is a real risk. Use Claude Code's permission allowlist + start with read-only directories until you trust the setup.
Why this is the right architecture (until Anthropic ships native)
Native voice + mobile from Anthropic is "soon" but has been soon for 12+ months. The iMessage approach uses primitives Apple maintains at scale, they don't break iMessage, ever. Indie code on top of that infrastructure inherits the reliability without owning it.
When Anthropic does ship native voice mode for everyone, this setup still works as the file/text fallback. You don't lose anything by adopting it now.