messages

Fuzzy search through Apple Messages using the messages CLI tool.

Installation

If the messages CLI is not installed, install it:

git clone https://github.com/cardmagic/messages.git
cd messages && make install

Requirements:

• macOS with Apple Messages
• Node.js 22+
• Full Disk Access for terminal (System Settings > Privacy & Security > Full Disk Access)

Triggers

Use this skill when user asks about:

• Finding or searching text messages
• Looking up conversations or chats
• Finding what someone said in iMessage
• Searching message history
• Who texted recently, recent messages, contacts

Proactive triggers: "find text", "search messages", "what did X say", "message from", "text about", "iMessage", "look up conversation", "who texted", "recent messages", "recent texts"

Browse Commands

For browsing recent messages and conversations (no search query needed):

# Show most recent messages (answers "who texted me?")
messages recent

# List contacts by recent activity
messages contacts --limit 10

# List conversations with message counts
messages conversations

# Show recent messages from/to a specific person
messages from "John"

# Show full conversation thread with someone
messages thread "John" --after 2024-12-01

Search Commands

For fuzzy searching through message content:

# Rebuild index and search (recommended)
messages index-and-search "search query"

# Search with filters
messages search "query" --from "John"
messages search "query" --after 2024-06-01
messages search "query" --limit 25
messages search "query" --context 5

# Combine options
messages search "dinner" --from "Mom" --after 2024-01-01 --limit 15

Other Commands

# Check index stats (message count, date range, etc.)
messages stats

# Rebuild index only
messages index

Options Reference

Tips

• Use quotes around multi-word search terms: "dinner plans"
• Sender filter supports partial matches: --from "John" matches "John Smith"
• Phone numbers can be used in sender filter: --from "+1555"
• Increase --limit for broader searches
• Increase --context to see more conversation around matches