iMessage & Signal Analyzer

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

Prerequisites

macOS (iMessage)

iMessage data is stored locally on macOS. Depending on your security settings, you may need to grant Full Disk Access:

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

First, export your Signal data (one-time):

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

If you have a name but not a number:

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%';"

If AddressBook returns no results, ask the user for the number.

Signal

Signal exports include phone numbers in the JSON. Search by name or number.

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

Present the analysis conversationally, not just as raw numbers. Offer a genuine take on the relationship dynamic.