iMessage & Signal Analyzer

Analyze iMessage (macOS) and Signal conversations to produce relationship reports.

Prerequisites

macOS (iMessage)

Option 1: Run the script directly with Python (no special permissions needed if you have read access to ~/Library/Messages/chat.db)

Option 2: If you get a permission error, grant Full Disk Access:

• Open System Settings → Privacy & Security → Full Disk Access
• Click + and add Python or your terminal app

Linux / Windows (Signal only)

• iMessage is not available on Linux/Windows
• Signal analysis works via exported JSON

Signal (All Platforms)

• Install signal-cli: brew install signal-cli (macOS) or see https://github.com/AsamK/signal-cli
• Link your device: signal-cli link and scan QR code
• Export messages: signal-cli export --output ~/signal_export.json

Usage

iMessage Analysis

python3 skills/message-analyzer/scripts/analyze.py imessage <phone_or_handle>

Examples:

python3 skills/message-analyzer/scripts/analyze.py imessage "+15551234567"
python3 skills/message-analyzer/scripts/analyze.py imessage "+15551234567" --limit 500

Signal Analysis

signal-cli export --output ~/signal_export.json

Then analyze:

python3 skills/message-analyzer/scripts/analyze.py signal ~/signal_export.json <phone_or_name>

Examples:

python3 skills/message-analyzer/scripts/analyze.py signal ~/signal_export.json "+15551234567"
python3 skills/message-analyzer/scripts/analyze.py signal ~/signal_export.json "+15559876543"

Finding a Contact's Number

iMessage

DB=$(ls ~/Library/Application\ Support/AddressBook/Sources/*/AddressBook-v22.abcddb 2>/dev/null | head -1)
sqlite3 "$DB" "SELECT ZFIRSTNAME, ZLASTNAME FROM ZABCDRECORD WHERE ZFIRSTNAME LIKE '%Name%';"

Signal

Key Data Caveats

iMessage

• Your sent messages may only exist from the current device's setup date — older sent messages are lost when switching devices. This skews initiation stats.
• Binary messages (attributedBody) are partially decoded — some formatting artifacts like +@ prefixes may appear in samples; these are normal.
• Multiple handles: One contact may have 2–3 duplicate handles (iMessage + SMS + RCS). The script aggregates them automatically.

Signal

• Export required: You must export Signal data first using signal-cli export
• Media: Exported JSON contains message text; media (images, files) is not included
• Reactions: Emoji reactions are included as separate message entries

Analysis Output

The script produces:

• Total message count (you vs. them)
• Date range
• Messages per year with volume bar
• Conversation initiation breakdown (new convo = gap > 4 hours)
• Notable silences (>30 days)
• Sample messages by year
• Most recent 10 messages

Interpreting Results

After running the script, synthesize findings conversationally:

• Volume patterns: When was the friendship most active? Any notable surges or drops?
• Initiation skew: Who reaches out first? (Note: your sent messages may be missing from old periods)
• Gaps: Were long silences mutual drift or explainable (device switch, platform change, life event)?
• Tone/content: What do the sample messages reveal about the relationship's energy?
• Context from user: Always ask the user to fill in context gaps