---

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:

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

If no arguments provided, show the Reference section below.

Command Mapping (use FIRST match)

Messaging & Reading

Groups & Media

Analytics & Discovery

Semantic Search (RAG)

---

Reference (shown when no arguments provided)

Performance

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

Copy# 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 +14155551234 "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