imessage-query_skill

Overview

This skill queries the macOS iMessage SQLite database (~/Library/Messages/chat.db) to retrieve conversation history, decode NSAttributedString blobs, and produce sourced timelines with accurate local timestamps. It safely uses read-only SQLite access and includes a robust three-tier decoder for attributedBody content. Use it to recover hidden text, search conversations, and export NDJSON for offline analysis.

How this skill works

The skill runs parameterized SQLite queries against chat.db to list chats, fetch message rows, and convert Apple epoch timestamps to localtime. When m.text is empty it decodes attributedBody using a three-tier strategy: optional pytypedstream deserialization, multi-format binary parsing, and a legacy NSString-length fallback. The decode script applies native protections (excludes retracted messages, flags edits, resolves replies, and surfaces attachments/effects).

When to use it

• Retrieve full iMessage history for a contact, including rich / dictated text
• Recover messages where text is NULL but attributedBody contains recoverable content
• Search keywords across conversations with contextual surrounding messages
• Build sourced timelines or export conversations for offline analysis
• Debug messages that appear empty or misclassified in the native client

Best practices

• Run with Full Disk Access and always use read-only SQLite connections
• Run --stats first to confirm the correct chat_identifier and date range
• Prefer export-first workflows: export NDJSON once, then grep/jq for repeated analysis
• Use --context N with --search to capture conversational meaning around matches
• Avoid querying many chat_identifiers blindly; narrow to the confirmed identifier

Example use cases

• Export a contact thread to NDJSON and run jq filters for sentiment or keyword frequency
• Recover dictated or richly formatted messages that show as empty in the Messages app
• Generate a sourced timeline for documentation or legal review with precise local timestamps
• Search a conversation for a meeting reference and include three messages of context around each hit
• Detect attachments, message effects, and edited messages while excluding retracted content