--- 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: ```bash 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 ` | `recent --limit --json` (default: 50) | | `find [for ""]` | `find "" [--query ""] --limit 50 --json` | | `messages ` \/ `from ` | `messages "" --limit 20 --json` | | `unread` | `unread --json` | | `send ` | `send "" ""` (no --json) | | `send-by-phone ` | `send-by-phone "" ""` | ### Groups & Media | User says | Execute | |-----------|---------| | `groups` | `groups --json` | | `attachments []` | `attachments [""] --json` | | `voice []` | `voice [""] --json` | | `links []` | `links --days --json` (default: 30) | ### Analytics & Discovery | User says | Execute | |-----------|---------| | `analytics [] []` | `analytics [""] --days --json` (default: 30) | | `followup []` | `followup --days --json` (default: 7) | | `contacts` | `contacts --json` | | `handles []` | `handles --days --json` (default: 30) | | `unknown []` | `unknown --days --json` (default: 7) | | `summary []` | `summary "" --days --json` (default: 7) | ### Semantic Search (RAG) | User says | Execute | |-----------|---------| | `search ""` | `search "" --json` | | `ask ""` | `ask "" --json` | | `index []` | `index --source= --json` (imessage, superwhisper, notes, local) | | `stats` | `stats --json` | | `sources` | `sources --json` | | `clear []` | `clear [--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 ` - Send to contact - `send-by-phone ` - Send to phone number - `add-contact ` - 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 ```bash # 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