name: sync-data-imessage description: > Fetch iMessage conversations from local macOS SQLite database into a JSON file. No classification, no actions — just data. Fast, no browser needed. allowed-tools: Read, Write, Edit, Bash(python3:*)

Sync iMessage Data

iMessage ingestion from local macOS databases. No browser, no API keys. Reads ~/Library/Messages/chat.db for messages and ~/Library/Application Support/AddressBook/ for contact name resolution. Fast — typically <2 seconds.

Output File

outputs/sync-data/imessage.json — full replacement on every run.

Schema

{
  "version": 1,
  "last_synced": "2026-02-11T09:00:00-08:00",
  "days_fetched": 14,
  "conversation_count": 50,
  "conversations": [
    {
      "name": "Jerry Wang",
      "isGroup": false,
      "chatIdentifier": "+16263195466",
      "lastActivity": "2026-02-11 07:19",
      "unreadCount": 0,
      "participants": [
        { "handle": "+16263195466", "name": "Jerry Wang" }
      ],
      "messages": [
        {
          "sender": "Jerry Wang",
          "timestamp": "2026-02-11 07:16",
          "content": "Message text here..."
        }
      ]
    }
  ]
}

Steps

1. Run: python3 scripts/imessage-sync.py --days 14 --count 50
2. Parse the JSON output. The script returns { "conversations": [...], "count": N }.
3. Build the output object with version, last_synced (current ISO timestamp with timezone offset), days_fetched (14), conversation_count, and conversations.
4. Write to outputs/sync-data/imessage.json (full replacement).
5. Log: "Synced {N} iMessage conversations at {timestamp}"

Notes

• Reads from ~/Library/Messages/chat.db (iMessage) and ~/Library/Application Support/AddressBook/ (Contacts).
• Contact name resolution uses the macOS AddressBook databases. Unresolved contacts show as phone numbers or emails.
• Short codes (5-6 digit numbers like 32024, 66458) are automated/2FA messages.
• The script filters out reactions/tapbacks (associated_message_type = 0) and empty messages.
• Typically takes <2 seconds.