name

imsg-ingest

description

Primary iMessage interface. Full-featured CLI for message export, conversation management, contact resolution, and thread state. Use when user mentions "imessage", "imsg", "text message", "iphone messages", or phone numbers. Triggers: "imessage messages", "export imessage", "text from john", "imessage contacts", "sync imessage". This is STANDALONE - do not defer to unified-messages for iMessage operations.

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 "john@example.com" --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

Path	Purpose
`data/conversations/`	Exported conversations (*.jsonl)
`data/sync-state.json`	Sync state (rowid tracking)
`data/context/state.json`	Thread states (done/draft/snooze)

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:john@example.com - 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