imessage-gateway

name	imessage-gateway
description	Complete iMessage CLI with semantic search. The only interface needed for iMessage on macOS. 19x faster than MCP.
version	4.0.0

EXECUTE IMMEDIATELY

ARGUMENTS: {{ARGUMENTS}}

When arguments are provided, execute via Bash NOW. Add --json flag for data retrieval commands:

python3 ${SKILL_PATH}/../../gateway/imessage_client.py {{ARGUMENTS}}

If no arguments provided, show the Reference section below.

Command Mapping (use FIRST match)

Messaging & Reading

User says	Execute
recent <N>	recent --limit <N> --json (default: 50)
find <contact> [for "<query>"]	find "<contact>" [--query "<query>"] --limit 50 --json
messages <name> / from <name>	messages "<name>" --limit 20 --json
unread	unread --json
send <name> <message>	send "<name>" "<message>" (no --json)
send-by-phone <phone> <message>	send-by-phone "<phone>" "<message>"

Groups & Media

User says	Execute
groups	groups --json
attachments [<contact>]	attachments ["<contact>"] --json
voice [<contact>]	voice ["<contact>"] --json
links [<days>]	links --days <N> --json (default: 30)

Analytics & Discovery

User says	Execute
analytics [<contact>] [<days>]	analytics ["<contact>"] --days <N> --json (default: 30)
followup [<days>]	followup --days <N> --json (default: 7)
contacts	contacts --json
handles [<days>]	handles --days <N> --json (default: 30)
unknown [<days>]	unknown --days <N> --json (default: 7)
summary <name> [<days>]	summary "<name>" --days <N> --json (default: 7)

Semantic Search (RAG)

User says	Execute
search "<query>"	search "<query>" --json
ask "<question>"	ask "<question>" --json
index [<source>]	index --source=<source> --json (imessage, superwhisper, notes, local)
stats	stats --json
sources	sources --json
clear [<source>]	clear [--source=<source>] --force --json

---

Reference (shown when no arguments provided)

Performance

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

All Commands (27 total)

Messaging (3)

• send <contact> <message> - Send to contact
• send-by-phone <phone> <message> - Send to phone number
• add-contact <name> <phone> - Add contact

Reading (12)

• messages, find, recent, unread, handles, unknown
• attachments, voice, links, thread, scheduled, summary

Groups (2)

• groups, group-messages

Analytics (3)

• analytics, followup, reactions

Contacts (1)

• contacts

Semantic Search/RAG (6)

• index - Index content for semantic search
• search - Semantic search across indexed content
• ask - Get AI-formatted context
• stats - Knowledge base statistics
• sources - List available/indexed sources
• clear - Clear indexed data

Full Command Examples

# Recent messages
python3 ${SKILL_PATH}/../../gateway/imessage_client.py recent --limit 50 --json

# Find messages with contact (keyword search)
python3 ${SKILL_PATH}/../../gateway/imessage_client.py find "John" --query "meeting" --limit 50 --json

# Messages from contact
python3 ${SKILL_PATH}/../../gateway/imessage_client.py messages "Ever" --limit 20 --json

# Unread messages
python3 ${SKILL_PATH}/../../gateway/imessage_client.py unread --json

# Send message
python3 ${SKILL_PATH}/../../gateway/imessage_client.py send "Sarah" "Running late!"

# Send directly to phone number
python3 ${SKILL_PATH}/../../gateway/imessage_client.py send-by-phone [phone] "Hi there!"

# Analytics for specific contact
python3 ${SKILL_PATH}/../../gateway/imessage_client.py analytics "John" --days 30 --json

# Follow-ups needed
python3 ${SKILL_PATH}/../../gateway/imessage_client.py followup --days 7 --json

# List groups
python3 ${SKILL_PATH}/../../gateway/imessage_client.py groups --json

# Semantic search (RAG)
python3 ${SKILL_PATH}/../../gateway/imessage_client.py search "dinner plans with Sarah" --json

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

# Index all local sources (SuperWhisper + Notes)
python3 ${SKILL_PATH}/../../gateway/imessage_client.py index --source=local

# Ask a question (AI-formatted context)
python3 ${SKILL_PATH}/../../gateway/imessage_client.py ask "What restaurant did Sarah recommend?"

# Knowledge base stats
python3 ${SKILL_PATH}/../../gateway/imessage_client.py stats --json

# List available sources
python3 ${SKILL_PATH}/../../gateway/imessage_client.py sources --json

Contact Resolution

Names are fuzzy-matched from config/contacts.json:

• "John" → "John Doe" (first match)
• "ang" → "Angus Smith" (partial)
• Case insensitive

Requirements

• macOS with Messages.app
• Python 3.9+
• Full Disk Access for Terminal
• Contacts synced via scripts/sync_contacts.py
• For RAG: OpenAI API key (OPENAI_API_KEY) or local embeddings