# 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
```bash
git clone https://github.com/yourusername/imessage-gateway.git
cd imessage-gateway
pip install -r requirements.txt
```
### 2. Set Up Contacts
```bash
# 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
```bash
# 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)
```bash
# 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)
```bash
# 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)
```bash
# 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)
```bash
# 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)
```bash
# List all contacts
python3 gateway/imessage_client.py contacts --json
```
### Semantic Search / RAG (6)
```bash
# 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`:
```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
```bash
# 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](LICENSE) for details.
---
*Built for use with [Claude Code](https://claude.ai/code)*
