imsg-ingest_skill

Overview

This skill provides a standalone, full-featured iMessage CLI for exporting messages, managing conversations, resolving contacts, and tracking thread state. It is designed for local use on a Mac with Full Disk Access and reads the system Messages database in read-only mode. Use it when you need reliable exports, syncs, or programmatic access to iPhone/iMessage data.

How this skill works

The tool inspects the macOS Messages SQLite database and maintains a local data directory with exported conversation JSONL files, sync state, and per-thread metadata. It offers commands to sync new or backfill older messages, list and filter conversations, dump single or all chats, and resolve contacts against the AddressBook. Thread states (drafts, pending, done, snooze) are stored in a JSON context file for lightweight workflow tracking.

When to use it

• Export a conversation for AI prompting or archival purposes.
• Sync new iMessage traffic into a local export store before processing.
• Resolve phone numbers or emails to contact names for cleaner exports.
• List or filter conversations to find active DMs or group chats quickly.
• Set or inspect thread state (pending/done/archived) for task-oriented messaging workflows.

Best practices

• Grant Full Disk Access before using the tool; it requires read access to ~/Library/Messages/chat.db.
• Run a sync before exporting to ensure you have the latest messages and correct rowid tracking.
• Use quick_export.py for Markdown-ready snippets when preparing AI prompts or clipboard copies.
• Limit dump-all runs with --min-messages or --limit-per-chat to avoid huge exports.
• Keep the data directory under versioned or backed-up storage if you need long-term archives.

Example use cases

• Quickly export the last 24 hours of a conversation to Markdown for feeding into an AI assistant.
• Backfill older messages when reconstructing a chat history for legal or project review.
• Batch-export all conversations with more than 10 messages for migration or analysis.
• Lookup a phone number to attach a contact name before sharing an export with a teammate.
• Mark a thread as pending with a short note and later mark it done to track follow-ups.