iMessage & Signal Analyzer

---

name: imessage-signal-analyzer description: Analyze iMessage (macOS) and Signal conversation history to reveal relationship dynamics — message volume, initiation patterns, silence gaps, tone samples, and recent exchanges. Use when asked to analyze messages, read message history, check conversation patterns, or evaluate a relationship based on text history. Works on macOS (iMessage + Signal), Linux/Windows (Signal only).

---

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 

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 

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.

iMessage Analysis

python3 skills/message-analyzer/scripts/analyze.py imessage 

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 

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"

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