iMessage Export (imsg-ingest)

iMessage Export (imsg-ingest)

Primary interface for all iMessage operations. Standalone and full-featured.

Location: /​Users/​satoshi/​data/​imsg-ingest

Quick Start

cd /​Users/​satoshi/​data/​imsg-ingest

# Check access (MUST have Full Disk Access)
poetry run imsg status

# Sync messages
poetry run imsg sync

# List conversations
poetry run imsg list

# Export specific conversation
poetry run imsg dump "+14155551234" --output john.jsonl

Prerequisites

Full Disk Access required. See references/​setup.md for setup.

Core Workflows

Quick Export for AI Context (Recommended)

Get recent messages as markdown, ready to paste into Claude:

# Syncs first, outputs to stdout (last 24h)
python scripts/​quick_export.py "+14155551234"

# By contact name
python scripts/​quick_export.py "John Doe" --hours 48

# Copy to clipboard
python scripts/​quick_export.py "+14155551234" | pbcopy

# Visual copy in browser
python scripts/​quick_export.py "+14155551234" | quick-view

# Intentional save
python scripts/​quick_export.py "+14155551234" --save
# → exports/​14155551234_2026-01-02.md

See references/​files.md for file management philosophy.

Export via CLI (Alternative)

# By phone number
poetry run imsg dump "+14155551234" --output john.jsonl

# By email
poetry run imsg dump "[email protected]" --output john.jsonl

# By name (searches contacts)
poetry run imsg dump "John Doe" --output john.jsonl

# Last 7 days only
poetry run imsg dump "+14155551234" --last 7d --output john.jsonl

Sync Operations

# Sync new messages (forward)
poetry run imsg sync

# Backfill older messages
poetry run imsg sync --backfill

List Conversations

# All conversations
poetry run imsg list

# DMs only
poetry run imsg list --no-groups

# Groups only
poetry run imsg list --no-dms

# With minimum message count
poetry run imsg list --min-messages 10

Export All Conversations

# Export all with 10+ messages
poetry run imsg dump-all --min-messages 10

# Limit messages per chat
poetry run imsg dump-all --limit-per-chat 500

Contact Resolution

# Check contact system status
poetry run imsg contacts status

# Lookup a contact
poetry run imsg contacts lookup "+14155551234"

# List all contacts
poetry run imsg contacts list

# Refresh contacts from AddressBook
poetry run imsg contacts sync

# Update exports with contact names
poetry run imsg contacts refresh-exports

See references/​contacts.md for resolution backends.

Data Locations

Source Database

~/​Library/​Messages/​chat.db

Read-only SQLite access. Requires Full Disk Access.

Thread ID Format

iMessage threads use format: imsg:dm:identifier or imsg:group:chatID

Examples:

• imsg:dm:+14155551234 - DM with phone number
• imsg:dm:[email protected] - DM with email
• imsg:group:chat123456 - Group chat

Thread State

State stored in data/​context/​state.json. Same format as tg-ingest:

{
  "imsg:dm:+14155551234": {
    "status": "pending",
    "draft": null,
    "note": "Follow up on project",
    "snooze": null
  }
}

States: pending, done, archived