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.
This skill hasn't been reviewed yet.
What it does
Searches and summarizes your Mac's local iMessage history so you can see past texts by keyword, sender, or date. Read-only, on-device. macOS only.
How to use this
Once it is installed, this skill picks itself up. You do not need to name it.
- Created by
- Darlin Alberto
- Category
- Productivity
- Source
- View source
Run this on Skills and Agents
You can run the skill on Skills and Agents by creating an account. You don't need to install anything. We provide the model and tokens. Your connected tools and company brain are ready to use.
Skills give you best practices and templates to get the most out of your AI
Add this skill
Pick where you want it. Nothing to configure after.
These install links go live once the signup flow ships. Until then, ask Claude, ChatGPT, or Gemini to fetch this skill's file directly from GitHub.
Not sure which? See the install guide.
Share this skill
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.
Third-party, by Darlin Alberto
May 14, 2026
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
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
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
Verify it works
Run a quick test against your local chat.db.
python3 scripts/imessage.py chats --limit 5 - 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.
Your skill is downloading.
Create a free account and the platform does the rest:
- Get an email the moment this skill updates
- See every skill and agent you've installed, in one place
- Get your next recommendation based on what you actually use
No credit card. Takes about a minute.
What this skill does
This is an overview of the skill from the site, not the skill's real instructions. The full SKILL.md Claude reads when this skill is active lives on GitHub at the source below.
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:
- The skill is installed (the
scripts/imessage.pyfile is reachable from the skill folder). - 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:
- Answer — a direct one or two sentence response to the question.
- Evidence — a short list of supporting messages with
[sender, timestamp] — text. - 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.
View full SKILL.md on GitHub