majiayu000 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:+14155551234orimsg:dm:email@example.com - iMessage Group:
imsg:group:chat123456
MCP Tools
| Tool | Purpose |
|---|---|
unified_search |
Search people/threads across platforms |
unified_inbox |
List threads needing attention |
unified_get_person |
Full context for a person (threads, messages, notes) |
unified_get_thread |
Messages and state for specific thread |
unified_save_draft |
Save draft reply |
unified_set_status |
Set pending/done/archived |
unified_snooze |
Snooze until datetime |
unified_add_note |
Add note to thread |
unified_sync |
Sync both platforms |
Workflows
Daily Triage
unified_sync- Pull latestunified_inbox- See what needs attention- Review each thread, then
set_status("done")orsave_draft()
Find a Person
unified_search("vibhu")- Returns person with all thread IDsunified_get_person("vibhu")- Full context with recent messages
Reply Workflow
unified_get_thread("tg:dm:username")- Read conversationunified_save_draft("tg:dm:username", "Draft...")- Save draft- Send manually in Telegram/iMessage
unified_set_status("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 for full CLI docs. See references/data-locations.md for data paths.