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