imessage

What it is

iMessage is a Claude Code channel plugin (version 0.2.0) that connects iMessage to your Claude Code assistant. It reads ~/Library/Messages/chat.db directly for history, search and new-message detection, and sends messages via AppleScript to Messages.app. It needs no external server and no background process to keep alive. It runs on macOS only. For inbound messages, the plugin polls chat.db once a second for rows with ROWID > watermark. The watermark starts at MAX(ROWID) at boot, so old messages aren't replayed on restart. Outbound messages go through osascript with tell application "Messages" to send …. The text and chat GUID are passed through argv, which avoids escaping problems. History and search use direct SQLite queries against chat.db, so the full history is available, not just messages received since the server started. For attachments, every inbound image is surfaced to the assistant as a local path it can Read (image_path, image_path_2, …). Outbound attachments are sent as separate messages after the text. The assistant gets two tools: - reply: sends to a chat using chat_id + text, with optional files, and auto-chunks text. - chat_messages: fetches recent history as DM or Group threads, 100 messages per chat by default. Access control is built in. By default you text yourself, and self-chat always bypasses the gate. Messages from other senders are dropped silently, with no auto-reply, until you allowlist their handle (a phone number or Apple ID email). Pairing, allowlists and policy are managed via /imessage:access. AppleScript cannot tapback, edit or thread messages; those need Apple's private API. The README points to BlueBubbles for those features, which requires disabling SIP.

Who it's for

• macOS users who want to chat with their Claude Code assistant over iMessage
• Developers who want the assistant to read and search their iMessage history
• Users who want a messaging channel without running an external server or background process

Requirements

Setup

1. Grant Full Disk Access

   chat.db is protected by macOS TCC. The first time the server reads it, macOS asks whether your terminal can access Messages; click Allow. If you click Don't Allow, or the prompt never appears, grant it manually: System Settings → Privacy & Security → Full Disk Access → add your terminal. Without this the server exits immediately with authorization denied.

2. Install the plugin

   These are Claude Code commands, so run claude to start a session first. No env vars are required.

   bashCopy

   /plugin install imessage@claude-plugins-official

3. Relaunch with the channel flag

   The server won't connect without this flag. Exit your session and start a new one, then check that /imessage:configure tab-completes.

   shCopy

   claude --channels plugin:imessage@claude-plugins-official

4. Text yourself

   iMessage yourself from any device. The message reaches the assistant immediately because self-chat bypasses access control. The first outbound reply triggers an Automation permission prompt ("Terminal wants to control Messages"); click OK.

5. Decide who else gets in

   Nobody else's texts reach the assistant until you add their handle. Handles are phone numbers or Apple ID emails.

   bashCopy

   /imessage:access allow +15551234567

Examples

/imessage:access allow +15551234567

claude --channels plugin:imessage@claude-plugins-official