iMessage

• Local — the Chat SDK bridge over chat-adapter-imessage (0.1.1, pinned), reading this Mac’s signed-in iMessage account (chat.db) directly. macOS only, and the Node binary needs Full Disk Access. It reads Messages on this Mac without a hosted iMessage relay, so NanoClaw must run on the Mac that’s signed in. Your configured model provider still processes the messages sent to the agent.
• Hosted — a native adapter connecting through Photon, a managed service that owns the iMessage line, delivery, and abuse prevention. The spectrum-ts SDK (11.0.0, pinned) holds a long-lived gRPC stream to Photon in-process on the host — no Mac relay, no webhook, no public URL. Works on any OS, and Photon offers a free tier to start with.

​

Prerequisites

• A working NanoClaw install (quickstart)
• Local backend: a Mac signed in to iMessage, and the ability to grant Full Disk Access in System Settings (the wizard walks you through it)
• Hosted backend: a photon.codes account (the wizard signs you in — free tier works) and the phone number you iMessage from, in +E.164 format

​

Install

​

Local backend: Full Disk Access

​

Hosted backend: Photon device login

1. Sign in — the terminal prints a URL and a short code (valid for about 30 minutes). Complete the sign-in on any device; the token is cached with 0600 permissions at data/photon-auth.json, so re-runs skip this step.
2. Project provisioning — the wizard creates or reuses a Photon project and its secret, regenerating the secret only when the API doesn’t return one.
3. Credentials written — PHOTON_PROJECT_ID and PHOTON_PROJECT_SECRET land in .env before the opt-in step.
4. Opt in with one text — the wizard registers your phone number with the project (it finds or creates the user entry itself) and prints the iMessage line Photon assigned to it. Send one message from your phone to that line: Photon marks the number opted in only after that first text. The wizard polls (10 minutes by default) until the opt-in lands rather than reporting success early. Re-runs reuse the existing registration, and an already-opted-in number passes immediately. The assigned number is recorded in data/photon-auth.json at the end.

​

Media and features (hosted)

• Inbound attachments and voice notes are read off the stream (with retry on transient failures) and staged into the session inbox, capped by PHOTON_MAX_INLINE_ATTACHMENT_BYTES (default 20 MB). Over-cap or failed attachments are skipped and annotated in the message text.
• Outbound files are sent as native attachments, before their caption text.
• Markdown is on by default (PHOTON_MARKDOWN=true) — iMessage renders it natively.
• Tapbacks work in both directions, and the adapter reports typing indicators and read receipts.
• Interactive questions (ask_user_question) arrive as messages whose answer commands are derived from the option labels (e.g. /approve, /reject).

​

Configuration reference

​

Platform notes

• Backend resolution is deterministic — an explicit IMESSAGE_BACKEND wins; otherwise Photon credentials imply hosted and IMESSAGE_ENABLED implies local. If both are configured without the selector, hosted wins and the adapter logs a warning. If neither backend has its credentials, the channel is skipped (a debug-level log line names both credential paths — visible only with LOG_LEVEL=debug).
• Switching backends — re-running /add-imessage (or imessage-configure.sh directly) rewrites IMESSAGE_BACKEND, and the explicit selector always beats leftover keys, so stale credentials from the other backend are ignored. Switching to hosted also removes IMESSAGE_ENABLED; switching to local leaves the PHOTON_* keys in place.
• Engage defaults — DMs engage on every message; in group chats the agent engages when its name is mentioned; unknown senders fall under the strict policy. See the entity model for how to change these per wiring.
• Platform IDs — DMs use the counterpart’s bare handle (+15551234567, or an email on local); hosted groups use the opaque Spectrum space ID.
• No threads — the adapter sets supportsThreads: false on both backends; thread IDs map 1:1 to conversations, so per-thread session mode behaves like shared here.

​

Troubleshooting

• iMessage channel never starts — the adapter needs its backend’s credentials: local needs IMESSAGE_ENABLED=true, hosted needs both PHOTON_PROJECT_ID and PHOTON_PROJECT_SECRET. When they’re missing the channel is skipped quietly — the log line naming both paths is debug-level, so set LOG_LEVEL=debug to see it. On hosted, grep "Photon channel connected" logs/nanoclaw.log confirms the stream is up.
• Inbound messages never arrive (local) — Full Disk Access is missing, or granted to a different node binary than the one the service runs under. Run open "$(dirname "$(which node)")", re-drag that node file into Full Disk Access, and restart the service.
• Target not allowed for this project (hosted) — the recipient’s number isn’t opted in to the line. Send one message from that phone to the line assigned to it, then retry. If the number was never registered, re-run /add-imessage; photon-setup.ts status re-checks the opt-in live.
• Device login timed out or the code expired (hosted) — the URL and code last about 30 minutes, and a failed login caches nothing. Re-run /add-imessage for a fresh URL and code; once a login has succeeded, re-runs skip sign-in via the cached token and reuse the already-provisioned project.
• spectrum-ts not installed (hosted) — the backend’s package didn’t land. Re-run /add-imessage and pick hosted; the install step is idempotent.
• Installed but silent — run the adapter’s registration test from your NanoClaw checkout: pnpm exec vitest run src/channels/imessage-registration.test.ts.
• “Couldn’t finish connecting” at the end of setup — the welcome message didn’t go out. Local: double-check Full Disk Access. Hosted: confirm you texted the assigned line once from your phone — that first text is the opt-in.