imessage-gateway

iMessage Gateway CLI

The fastest iMessage integration for Claude Code. Direct CLI architecture delivers 19x faster performance than MCP-based alternatives.

Features

• Send Messages: Send iMessages using natural language
• Read Messages: Retrieve message history with contacts or phone numbers
• Smart Contact Lookup: Fuzzy matching for contact names
• Semantic Search (RAG): AI-powered search across iMessages, SuperWhisper, Notes
• Follow-up Detection: Find conversations needing response
• Group Chats: List and read group conversations
• Analytics: Conversation patterns and statistics

Performance

Operation	Gateway CLI	MCP-based	Speedup
List contacts	40ms	~763ms	19x
Find messages	43ms	~763ms	18x
Unread messages	44ms	~763ms	17x
Groups	61ms	~763ms	12x
Semantic search	150ms	~900ms	6x

Requirements

• macOS (required - iMessage is macOS only)
• Python 3.9+
• Full Disk Access permission (for reading message history)

Quick Start

1. Clone and Install

git clone https://github.com/yourusername/imessage-gateway.git
cd imessage-gateway
pip install -r requirements.txt

2. Set Up Contacts

# Sync from macOS Contacts (recommended)
python3 scripts/sync_contacts.py

# Or manual setup
cp config/contacts.example.json config/contacts.json
# Edit config/contacts.json with your contacts

3. Grant Permissions

1. Full Disk Access (for reading messages):

   • System Settings → Privacy & Security → Full Disk Access
   • Add Terminal.app or your Python interpreter

2. Automation (for sending messages):

   • Will be requested automatically on first send

4. Test It Out

# List your contacts
python3 gateway/imessage_client.py contacts --json

# Check unread messages
python3 gateway/imessage_client.py unread --json

# Get recent messages
python3 gateway/imessage_client.py recent --limit 20 --json

# Send a message
python3 gateway/imessage_client.py send "John" "Hey, are you free for coffee?"

Command Reference (27 Commands)

Messaging (3)

# Send to contact
python3 gateway/imessage_client.py send "John" "Hello!"

# Send to phone number directly
python3 gateway/imessage_client.py send-by-phone "+14155551234" "Hi there!"

# Add a new contact
python3 gateway/imessage_client.py add-contact "Jane Doe" "+14155559876"

Reading (12)

# Messages with a contact
python3 gateway/imessage_client.py messages "John" --limit 20 --json

# Find messages (keyword search)
python3 gateway/imessage_client.py find "John" --query "meeting" --json

# Recent across all contacts
python3 gateway/imessage_client.py recent --limit 50 --json

# Unread messages
python3 gateway/imessage_client.py unread --json

# Recent phone handles
python3 gateway/imessage_client.py handles --days 30 --json

# Messages from unknown senders
python3 gateway/imessage_client.py unknown --days 7 --json

# Attachments
python3 gateway/imessage_client.py attachments "John" --json

# Voice messages
python3 gateway/imessage_client.py voice --json

# Links shared
python3 gateway/imessage_client.py links --days 30 --json

# Message thread
python3 gateway/imessage_client.py thread "<message-guid>" --json

# Scheduled messages
python3 gateway/imessage_client.py scheduled --json

# Conversation summary
python3 gateway/imessage_client.py summary "John" --days 7 --json

Groups (2)

# List group chats
python3 gateway/imessage_client.py groups --json

# Messages from a group
python3 gateway/imessage_client.py group-messages --group-id "chat123456" --json

Analytics (3)

# Conversation analytics
python3 gateway/imessage_client.py analytics "John" --days 30 --json

# Follow-ups needed
python3 gateway/imessage_client.py followup --days 7 --json

# Reactions
python3 gateway/imessage_client.py reactions "John" --json

Contacts (1)

# List all contacts
python3 gateway/imessage_client.py contacts --json

Semantic Search / RAG (6)

# Index iMessages for semantic search
python3 gateway/imessage_client.py index --source=imessage --days 30

# Index SuperWhisper transcriptions
python3 gateway/imessage_client.py index --source=superwhisper

# Index Notes
python3 gateway/imessage_client.py index --source=notes

# Index all local sources
python3 gateway/imessage_client.py index --source=local

# Semantic search
python3 gateway/imessage_client.py search "dinner plans with Sarah" --json

# AI-formatted context
python3 gateway/imessage_client.py ask "What restaurant did Sarah recommend?"