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?"

# Knowledge base stats
python3 gateway/imessage_client.py stats --json

# List available/indexed sources
python3 gateway/imessage_client.py sources --json

# Clear indexed data
python3 gateway/imessage_client.py clear --source=imessage --force

Architecture

Messages.db (SQLite) ←─ ~/Library/Messages/chat.db
        ↓
MessagesInterface ────→ SQLite queries (read)
        │                AppleScript → Messages.app (send)
        ↓
ContactsManager ──────→ config/contacts.json (fuzzy matching)
        ↓
Gateway CLI ──────────→ gateway/imessage_client.py
        ↓
Claude Code ──────────→ Bash tool calls

Why Gateway CLI?

The Gateway CLI architecture bypasses MCP framework overhead entirely:

• Direct execution: Python script runs immediately, no JSON-RPC initialization
• No session startup: MCP servers have ~700-800ms cold start per session
• Smaller footprint: No MCP SDK dependency, simpler codebase
• Same reliability: Uses identical MessagesInterface code for all operations

Claude Code Integration

Using the Skill

The imessage-gateway skill provides natural language access:

/imessage-gateway unread
/imessage-gateway send John "Running late!"
/imessage-gateway search "meeting next week"

Bash Pre-approval

Ensure your settings include:

Bash(python3:*::*)

Configuration

Contact Format

Contacts are stored in config/contacts.json:

{
  "contacts": [
    {
      "name": "John Doe",
      "phone": "14155551234",
      "relationship_type": "friend",
      "notes": "Optional notes"
    }
  ]
}

Phone numbers can be in any format - they're normalized automatically.

Troubleshooting

"Contact not found"

• Run python3 scripts/sync_contacts.py to sync contacts
• Check config/contacts.json exists and has contacts
• Try partial names (e.g., "John" instead of "John Doe")

"Permission denied" reading messages

• Grant Full Disk Access to Terminal/Python
• Restart Terminal after granting permission
• Verify: ls ~/Library/Messages/chat.db

Messages show "[message content not available]"

• Some older messages use a different format
• Attachment-only messages don't have text content
• This is normal for some message types

Development

# Run tests
pytest tests/ -v

# Run performance benchmarks
python3 -m Texting.benchmarks.run_benchmarks

# Sync contacts
python3 scripts/sync_contacts.py

Privacy & Security

• All data stays local on your Mac
• No cloud services for core functionality
• Contacts file is gitignored by default
• Message history accessed read-only
• Optional OpenAI API for semantic search embeddings

MCP Server (Archived)

The MCP server has been archived in mcp_server_archive/. See mcp_server_archive/ARCHIVED.md for restoration instructions if needed.

License

MIT License - see LICENSE for details.

---

Built for use with Claude Code