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
-
Full Disk Access (for reading messages):
- System Settings → Privacy & Security → Full Disk Access
- Add Terminal.app or your Python interpreter
-
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?"
