iMessage

How it works

The /add-imessage skill connects NanoClaw to iMessage in one of two ways:

• Local mode runs on macOS and reads the iMessage chat database directly. No external service, no API key — but the host must be the same Mac that’s logged into iMessage, and the Node.js binary needs Full Disk Access.
• Remote mode uses Photon as a relay. NanoClaw can run anywhere and Photon delivers iMessages over its API.

Setup

The skill copies the iMessage adapter from the channels branch and installs the chat-adapter-imessage package.

For local mode, the skill opens the Finder folder containing your Node binary so you can drag it into System Settings → Privacy & Security → Full Disk Access. The Node path is usually buried inside ~/.nvm/versions/node/..., so this saves a lot of clicking.

For remote mode, you sign up at photon.im, grab a server URL and API key, and drop both into .env.

What you get

• 1:1 conversations identified by phone number (+15551234567) or email address.
• Group chats with iMessage’s internal group IDs.
• No webhooks, no public URL in local mode — it just tails the chat database.
• Cross-device messaging in remote mode — runs the bot on a server even if you don’t keep a Mac online.

Tips

• Local mode is simpler if you already have a Mac running 24/7. Remote mode is the answer when you don’t.
• The Full Disk Access prompt is non-obvious — System Settings won’t open the right folder for you, which is why the skill opens it for you.
• Wire iMessage to the same agent group as your other personal channels if you want one assistant with shared memory across DMs.
• Use a separate agent group when different contacts should not share information — iMessage groups everything by phone/email, so the only privacy boundary is the agent group itself.