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 contactsend-by-phone <phone> <message>- Send to phone numberadd-contact <name> <phone>- Add contact
Reading (12)
messages,find,recent,unread,handles,unknownattachments,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 searchsearch- Semantic search across indexed contentask- Get AI-formatted contextstats- Knowledge base statisticssources- List available/indexed sourcesclear- 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