imessage-gateway

What this skill does

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

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