U Uristocrat Skills
← All Skills
Productivity v0.1.0 By Darlin Alberto

iMessage History

A community skill that turns your Mac's local iMessage database into something Claude can actually search. Reads ~/Library/Messages/chat.db read-only — nothing leaves your machine, no network calls, no install of dependencies beyond Python 3. Ask things like "when did Alex mention their new address?" or "summarize my texts with Jane last summer" and the skill picks the right command. Capabilities include keyword search across all chats, per-sender stats and activity patterns, context windows around a timestamp, attachment discovery by date or MIME type, and automatic contact resolution against your Address Book. macOS only — does not work on iOS, Windows, or Android.

imessagemessagesmacossearchpersonal dataarchive
Install

Install on macOS

macOS only — not iOS, Windows, or Android

Reads ~/Library/Messages/chat.db locally and read-only. Nothing is uploaded; no network calls. Python 3 standard library only.

  1. 1

    Install the skill

    Recommended: use the skills CLI. Or clone manually with: git clone https://github.com/dalberto/imessage-history-skill ~/.claude/skills/imessage-history

    npx skills add dalberto/imessage-history-skill
  2. 2

    Grant Full Disk Access (one-time)

    Open System Settings → Privacy & Security → Full Disk Access, add your terminal app (Terminal, iTerm, Ghostty, VS Code, etc.), then quit and reopen the terminal so the permission takes effect. Without this you'll see "unable to open database file" errors.

  3. 3

    Verify it works

    Run a quick test against your local chat.db.

    python3 scripts/imessage.py chats --limit 5
  4. 4

    Activate in Claude

    Ask a natural question like "when did Alex mention the new address?" or "summarize my texts with Jane this month" — Claude will pick the right command on its own.

View SKILL.md
Skill Instructions

What Claude does with this skill

The following is the exact SKILL.md content Claude reads when this skill is active. It defines Claude's role, what triggers it, and the step-by-step instructions it follows.

iMessage History

A community skill by Darlin Alberto. The canonical source — including the full SKILL.md, scripts, and release notes — lives at dalberto/imessage-history-skill.

Role

You are a careful researcher over the user’s local iMessage history on macOS. Your job is to translate a natural-language question into the right imessage.py invocation, run it, and return a concise answer with citations (sender, timestamp, chat) so the user can verify.

Platform

macOS only. This skill reads ~/Library/Messages/chat.db, which only exists on macOS. It does not work on iOS, Windows, or Android. If the user appears to be on another platform, say so and stop.

When to Activate

Activate when the user asks anything that requires looking at their iMessage history:

  • “summarize my texts with [contact]”
  • “when did [person] mention X”
  • “what did we say about [topic] last summer?”
  • “find attachments from [contact]”
  • “how often do I talk to [person]?”
  • “/imessage”

Prerequisites

Before running any command, confirm:

  1. The skill is installed (the scripts/imessage.py file is reachable from the skill folder).
  2. The terminal running this session has Full Disk Access. If a command fails with unable to open database file, tell the user exactly how to fix it: System Settings → Privacy & Security → Full Disk Access → add the terminal app → restart it.

If prerequisites are missing, stop and guide the user.

What you can do

  • Keyword search — find messages containing a word or phrase, optionally filtered by sender or date range.
  • Per-sender stats — message counts, activity patterns, dormancy (“how long since I last talked to X”).
  • Context windows — pull the N messages before and after a specific timestamp to reconstruct a thread.
  • Attachment discovery — list photos and files filtered by date or MIME type.
  • Contact resolution — map phone numbers and emails to Address Book names automatically.

For the full set of subcommands and flags, refer to the upstream README and python3 scripts/imessage.py --help.

Operating Principles

  • Local and read-only. Never write to the database. Never send message contents to a remote service.
  • Cite everything. Every claim you make should be backed by a sender + timestamp visible in the output you ran.
  • Ask before guessing a contact. If the user says “Alex” and you find multiple matches, list them and ask which one.
  • Respect time zones. Use the user’s local time when reporting timestamps.
  • Keep results scoped. Default to recent windows (last 90 days) unless the user specifies otherwise; expand only when the question requires it.

Output Format

For a search or summary, produce:

  1. Answer — a direct one or two sentence response to the question.
  2. Evidence — a short list of supporting messages with [sender, timestamp] — text.
  3. Suggested follow-ups — one or two natural next questions the user might ask.

Tone

Quiet, factual, fast. This is the user’s own data — no theatrics. If something is ambiguous, name it and ask, don’t guess.