unified-messages

Original source / Raw SKILL.md

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


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/cli-commands.md

```markdown
# Unified CLI Commands

Cross-platform aggregator commands. For platform-specific commands, see:
- **tg-ingest skill** for Telegram operations
- **imsg-ingest skill** for iMessage operations

## unified-messages CLI

Working directory: `/Users/satoshi/data/unified-messages`

```bash
python -m unified.cli <command>
```

### sync

```bash
python -m unified.cli sync [OPTIONS]
```

Sync messages from both Telegram and iMessage.

Options:
- `--backfill` - Fetch older messages instead of newer
- `--tg-only` - Only sync Telegram
- `--imsg-only` - Only sync iMessage

### status

```bash
python -m unified.cli status [OPTIONS]
```

Show sync status for both platforms.

Options:
- `--detailed, -d` - Show conversation-level details

### list

```bash
python -m unified.cli list [OPTIONS]
```

List pending threads across both platforms.

Options:
- `--limit, -n` - Maximum threads to show (default: 20)
- `--json` - Output as JSON

### generate

```bash
python -m unified.cli generate
```

Generate triage prompt for Claude. Outputs to `output/prompt.md`.

### render

```bash
python -m unified.cli render <RESPONSE_FILE>
```

Render Claude's triage response to HTML. Opens in browser.

```

### references/data-locations.md

```markdown
# Unified Data Locations

Cross-platform aggregator data. For platform-specific data, see:
- **tg-ingest skill** for Telegram data locations
- **imsg-ingest skill** for iMessage data locations

## File Management Philosophy

| Intent | Destination | Lifetime |
|--------|-------------|----------|
| Sync/store | `data/` | Permanent |
| Quick look | stdout | Seconds |
| Copy-paste | stdout → `pbcopy` or `quick-view` | Minutes |
| Save for later | `exports/` with timestamp | Permanent |
| Generated artifacts | `output/` | Semi-permanent |

**Rule: Ephemeral output goes to stdout.** No temp files for quick exports.

## unified-messages

**Base**: `/Users/satoshi/data/unified-messages`

| Path | Purpose |
|------|---------|
| `data/contacts.json` | Person registry (aliases, thread mappings) |
| `output/prompt.md` | Generated triage prompt |
| `output/triage.html` | Rendered triage output |

### contacts.json Format (Person Registry)

Maps person slugs to their threads across platforms:

```json
{
  "people": {
    "vibhu": {
      "display_name": "Vibhu Norby",
      "thread_ids": ["tg:dm:vibhu", "imsg:dm:+14155551234"],
      "primary": "tg:dm:vibhu",
      "aliases": ["v", "vn"],
      "notes": "Founder of X"
    }
  }
}
```

## Platform Data (Aggregated From)

unified-messages reads from these platform repos:

| Platform | Base Path | State File |
|----------|-----------|------------|
| Telegram | `/Users/satoshi/data/tg-ingest` | `data/decisions.jsonl` |
| iMessage | `/Users/satoshi/data/imsg-ingest` | `data/context/state.json` |

## Environment Variables

```bash
TG_INGEST_PATH=/Users/satoshi/data/tg-ingest
IMSG_INGEST_PATH=/Users/satoshi/data/imsg-ingest
```

```