Unified Messages

Cross-platform aggregator for Telegram + iMessage. Use when no platform specified.

If user says "telegram" → use tg-ingest skill
If user says "imessage" → use imsg-ingest skill
If user says "messages" (no platform) → use this skill

Quick Start

# Sync both platforms
python -m unified.cli sync

# List pending threads
python -m unified.cli list

# Check status
python -m unified.cli status --detailed

Thread ID Format

All threads use canonical IDs:

• Telegram DM: tg:dm:username (e.g., tg:dm:vibhu)
• Telegram Group: tg:group:slug (e.g., tg:group:crypto_trenches)
• iMessage DM: imsg:dm:+14155551234 or imsg:dm:[email protected]
• iMessage Group: imsg:group:chat123456

MCP Tools

Workflows

Daily Triage

1. unified_sync - Pull latest
2. unified_inbox - See what needs attention
3. Review each thread, then setstatus("done") or savedraft()

Find a Person

1. unified_search("vibhu") - Returns person with all thread IDs
2. unifiedgetperson("vibhu") - Full context with recent messages

Reply Workflow

1. unifiedgetthread("tg:dm:username") - Read conversation
2. unifiedsavedraft("tg:dm:username", "Draft...") - Save draft
3. Send manually in Telegram/iMessage
4. unifiedsetstatus("tg:dm:username", "done") - Mark complete

Project Structure

unified-messages/
├── unified/
│   ├── cli.py          # CLI (sync, status, list, generate, render)
│   ├── aggregator.py   # Cross-platform search, inbox, sync
│   ├── router.py       # Routes to correct platform
│   ├── contacts.py     # Person-centric contact resolution
│   └── triage.py       # Triage context generation
├── mcp_server.py       # MCP server (9 tools)
└── data/contacts.json  # Person registry

Platform Dependencies

Imports from sibling repos:

• tg-ingest/ - Telegram (Telethon)
• imsg-ingest/ - iMessage (SQLite chat.db)

See [references/cli-commands.md](references/cli-commands.md) for full CLI docs. See [references/data-locations.md](references/data-locations.md) for data paths.