playbooks

home / skills / rohunvora / cool-claude-skills / unified-messages

unified-messages skill

/skills/unified-messages

This skill aggregates messages across Telegram and iMessage when no platform is specified, offering unified inbox, search, and triage.

npx playbooks add skill rohunvora/cool-claude-skills --skill unified-messages

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
3.0 KB
---
name: unified-messages
description: >
  Cross-platform messaging aggregator. Use as DEFAULT when user does NOT
  specify a platform (telegram/imessage). Provides unified inbox, search,
  and triage across both platforms. Triggers: "check messages" (no platform),
  "inbox", "who messaged me", "all my messages", "triage". NOT for platform-
  specific requests - use tg-ingest for "telegram X" or imsg-ingest for
  "imessage X".
---

# 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

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

| 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
1. `unified_sync` - Pull latest
2. `unified_inbox` - See what needs attention
3. Review each thread, then `set_status("done")` or `save_draft()`

### Find a Person
1. `unified_search("vibhu")` - Returns person with all thread IDs
2. `unified_get_person("vibhu")` - Full context with recent messages

### Reply Workflow
1. `unified_get_thread("tg:dm:username")` - Read conversation
2. `unified_save_draft("tg:dm:username", "Draft...")` - Save draft
3. Send manually in Telegram/iMessage
4. `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](references/cli-commands.md) for full CLI docs.
See [references/data-locations.md](references/data-locations.md) for data paths.

Overview

This skill is a cross-platform messaging aggregator that provides a unified inbox, search, and triage for Telegram and iMessage when the user does not specify a platform. Use it as the default handler for generic requests like “check messages”, “inbox”, or “who messaged me”. It routes platform-specific queries to the appropriate ingest skill and consolidates threads, drafts, and statuses into one view.

How this skill works

It syncs message data from both Telegram and iMessage, normalizes threads into canonical IDs, and exposes tools to search, list pending threads, and manage triage state. Key operations include unified_search, unified_inbox, unified_get_person, unified_get_thread, saving drafts, setting status (pending/done/archived), snoozing, and adding notes. For platform-specific commands that mention “telegram” or “imessage”, this skill defers to the respective ingest skill.

When to use it

  • User asks about messages without naming a platform (e.g., “check messages”, “inbox”, “who messaged me”).
  • You want a single view across Telegram and iMessage to triage conversations.
  • Searching for a person or thread across both platforms.
  • Running a daily triage routine to mark messages done or save drafts.
  • Quickly review pending threads without switching apps.

Best practices

  • Run a sync before triage to ensure fresh data (unified_sync).
  • Use canonical thread IDs when saving drafts or changing status to avoid ambiguity (e.g., tg:dm:username, imsg:dm:+1415...).
  • Prefer unified_search to discover people and associated threads before fetching full context.
  • Use save_draft to compose replies inside the aggregator, then send via the native app and set_status("done").
  • Do not use this skill for platform-specific requests that explicitly name Telegram or iMessage—call the platform ingest skill instead.

Example use cases

  • Daily morning triage: unified_sync → unified_inbox → review threads → set_status("done") or save_draft().
  • Find all conversations with a contact: unified_search("alice") → unified_get_person("alice").
  • Inspect a thread quickly: unified_get_thread("tg:dm:username") to read recent messages and notes.
  • Snooze an active thread until a meeting ends: unified_snooze(thread_id, datetime).
  • Add contextual notes to a thread before handing it off or marking complete: unified_add_note(thread_id, "follow up about pricing").

FAQ

What do I do if I mention a platform explicitly?

If the user says “telegram” or “imessage”, this skill defers to the respective ingest skill (tg-ingest or imsg-ingest) for platform-specific operations.

How are threads identified?

Threads use canonical IDs: tg:dm:username, tg:group:slug, imsg:dm:+E164 or imsg:group:chatID—use these when saving drafts or setting status.