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 +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
