Skip to content
Get packs

Guide · Agent skill

How to use the Add iMessage Channel agent skill (add-imessage)

Updated · written with AI from the project's own documentation and checked against our catalogue data

The add-imessage skill teaches an AI agent to connect NanoClaw, an agent framework, to iMessage so the agent can read and reply to messages. It offers two backends: reading the iMessage account signed in on a Mac, or using a hosted iMessage line through photon.codes that works on any operating system. This guide explains what the skill does, how to install it, how to trigger it, and what it needs and touches before you run it.

Add iMessage Channelnanocoai/nanoclaw · MIT

Quick start

  1. 1Install the skill. Download the ZIP from the page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
  2. 2Open your NanoClaw project. Make sure the NanoClaw repository is available with pnpm, Node.js and the channels branch.
  3. 3Ask the agent to add iMessage. Use a request such as "add imessage" or "connect imessage" so the agent starts the skill.
  4. 4Choose a backend. Answer local for this Mac's signed-in account or hosted for a photon.codes line. Local stops with a message if you are not on macOS.
  5. 5Grant Full Disk Access for local. If you chose local, add Node in System Settings under Privacy & Security, then Full Disk Access, and confirm to the agent.
  6. 6Complete hosted device login. If you chose hosted, enter your phone number, open the login URL, enter the code, and send one message from your phone to the assigned line.
  7. 7Check the build and tests. Let the agent run the build and the registration test, and confirm they pass.

What is an agent skill?

An agent skill is a folder containing a SKILL.md file and supporting files that an AI agent reads to learn a specific task. When you ask for something that matches the skill's description, the agent follows the instructions in that folder.

This skill's SKILL.md describes the steps for adding iMessage to a NanoClaw project. The files in the package are apply-fixtures.json, docs.md, REMOVE.md and SKILL.md.

What the add-imessage skill makes the agent do

The skill adds a single imessage channel to NanoClaw. The agent first asks which backend to use, then copies the unified iMessage adapter from the channels branch into src/channels/, registers it in the channel barrel, installs a pinned package, and runs build and test checks.

Only one backend runs per install. The local backend reads this Mac's signed-in iMessage account through chat.db and requires macOS with Full Disk Access. The hosted backend uses Photon's spectrum-ts through photon.codes and works on any OS, with no Mac relay, webhook or public URL.

  • Local: chat-adapter-imessage@0.1.1, macOS only, Full Disk Access granted to Node.
  • Hosted: spectrum-ts@11.0.0 plus a photon.codes account and a device-login step.
  • Packages are pinned to exact versions; the skill does not use latest.

Install the add-imessage skill

Option 1: download the ZIP from the page, then unzip it into ~/.claude/skills/ to make it available to your user account, or into a project's .claude/skills/ folder to limit it to that project.

Option 2: in the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.

The skill applies to a NanoClaw repository, so you also need that project with pnpm, Node.js and the channels git branch available.

  • Unzip target for all projects: ~/.claude/skills/
  • Unzip target for one project: .claude/skills/ inside that project
  • Claude apps: Settings → Capabilities → Skills

Requirements before you start

The skill assumes you already run the NanoClaw project, because its steps depend on that project's build, test and config scripts. Choose the requirements that match your backend.

  • NanoClaw repository with pnpm, Node.js and the channels git branch
  • Local backend: macOS and Full Disk Access; chat-adapter-imessage@0.1.1
  • Hosted backend: spectrum-ts@11.0.0 and a photon.codes account
  • The skill runs scripts and uses the network

Trigger the skill with natural requests

The skill's description lists phrases that should activate it. You do not need to type a command; ask the agent in plain language. The listed triggers are the following.

  • "add imessage"
  • "connect imessage"
  • "add photon"
  • "imessage via photon"
  • "native imessage"

Safety notes: scripts, network and chat history

The skill runs shell scripts, installs packages and uses the network. The local backend reads the entire chat history of the Mac it runs on, so granting Full Disk Access to Node gives it that broad access. The skill's own text says to grant it only if you accept that.

The hosted backend requires your iMessage phone number in E.164 format, such as +14155551234. The skill notes that a number only enters routing after it has texted its assigned line once.

The skill's removal guide, REMOVE.md, deletes the adapter files, removes the import line and uninstalls the packages. It states that the provisioning script scripts/photon-setup.ts stays in place.

  • Do not use this skill if you will not grant Full Disk Access to Node for the local backend.
  • Review the scripts before running the skill if you want to check what the agent executes.
  • Use REMOVE.md to reverse the installation.

What people use it for

  • Letting a NanoClaw agent read and reply to messages from your own iMessage account on a Mac.
  • Giving a NanoClaw agent an iMessage line on a Linux or Windows machine through the hosted backend.
  • Testing the channel wiring with the registration test before you use it for real conversations.
  • Removing iMessage from a project later using REMOVE.md.

Frequently asked questions

Is the add-imessage skill free?

The source does not state a licence fee for the skill itself beyond naming its licence as MIT. The docs say Photon's free tier uses a shared iMessage line pool, so you can start without a paid plan.

What license is the add-imessage skill under?

The skill is listed under the MIT licence. Check the repository for the full licence text before you reuse the code.

Do I need a Mac to use add-imessage?

No, if you choose the hosted backend, which works on any OS through photon.codes. The local backend needs macOS because it reads chat.db on that Mac and needs Full Disk Access.

How do I install the add-imessage skill?

Download the ZIP from the page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. In the Claude apps, you can instead upload it under Settings → Capabilities → Skills.

Why does the local backend need Full Disk Access?

The adapter reads this Mac's chat.db, which requires Full Disk Access for the Node binary the host runs under. The skill opens the Node folder in Finder so you can drag the node file into the settings panel.

How do I remove the add-imessage changes?

Use REMOVE.md, which deletes the import line, removes the adapter and test files, and uninstalls the chosen backend's package. Its steps are written to be safe to re-run.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you already run NanoClaw and want your agent reachable over iMessage, either from your own Mac account or through a hosted line on another OS. Skip it if you will not grant Full Disk Access to Node for the local backend, or if you do not use the NanoClaw project, since the steps depend on its scripts.

Download the skill