imessage-skill

An Agent Skill that lets AI agents read your iMessage, SMS, and RCS conversations on macOS.

Install

npx skills add br-schneider/imessage-skill

Or copy the whole folder into your agent's skills directory, keeping scripts/ next to SKILL.md:

# Claude Code (global)
cp -R . ~/.claude/skills/imessage

# Claude Code (project)
cp -R . .claude/skills/imessage

What it does

• Reads conversations from ~/Library/Messages/chat.db
• Decodes all message types: iMessage, SMS, and RCS (including attributedBody blobs with multi-byte length encoding)
• Resolves contact names from the macOS AddressBook database
• Filters by contact name, phone number, or group chat name
• Filters by date (today, last N days, specific date) or from a time onward (--since 14:30), so an agent can follow a live conversation without re-reading it
• Searches message text (--search), keeping each match's date
• Lists chats newest first, for one person or across the whole database, with each chat's ROWID and when and how its last message arrived
• Reads several chats in one call (repeat --chat-id), each in its own section
• --limit always keeps the newest messages and says so when it cuts anything
• When a read comes back empty, explains why and points at the chat that does have messages
• Surfaces attachments inline as [attachment: <mime>, <absolute_path>] so the agent can read the file directly (filters out link-preview rows automatically)
• Optional --convert-heic flag to auto-convert HEIC to JPEG via sips, with idempotent caching at /tmp/imessage-attachments/<rowid>-<basename>.jpg
• Read-only database access, zero external dependencies (Python stdlib only)

Usage

Once installed, ask your agent naturally:

• "Read my messages with Mom"
• "What did John text me today?"
• "Show me the Family group chat from last week"
• "Read my texts with +15551234567 from March 29"
• "Anything new from Dad since 2pm?"
• "Find the TikTok Maddie sent me last month"

The agent will run the script and present the conversation.

Requirements

• macOS 14+
• Messages.app signed in
• Full Disk Access for your terminal (System Settings > Privacy & Security > Full Disk Access)
• Python 3.10+

How the blob parser works

Apple's Messages database stores SMS/RCS message text in an attributedBody blob column using the typedstream format, not the plain text column. This skill decodes these blobs by:

1. Finding the NSString marker in the binary data
2. Locating the type marker (0x2B or 0x2A)
3. Reading the length (single byte for messages up to 127 chars, 0x81 + 2-byte little-endian for longer messages)
4. Extracting exactly that many bytes as UTF-8 text

License

MIT