Ask questions about your entire iMessage history — from an AI agent, the terminal, or a Python notebook. Works on Mac.
- Ask your AI — connect to Claude, Codex, Cursor, or ChatGPT and ask things like "Who do I text most?" or "What did Alice and I talk about last month?"
- Search and query — run any question against your messages from the terminal
- Python notebooks — load your message data into pandas for custom analysis
- Always current — syncs only new messages each run, so it stays fast
- Real names — reads your Contacts to show names instead of phone numbers
1. Install the skills package:
npx skills add DecisionNerd/imessage-analysis2. Run the setup command inside your AI tool:
/imessage-analysis-install
This installs the binary, connects it to your AI tool, and walks you through the first sync — including a note about using Apple Terminal the first time so macOS can ask for Contacts permission.
3. Ask anything:
"Who have I texted most this year?" "Give me a deep dive on Alice" "Who's been waiting on a reply from me?"
curl -fsSL https://raw.githubusercontent.com/DecisionNerd/imessage-analysis/main/scripts/install.sh | bashDetects and connects to Claude Desktop, Cursor, Claude Code, and Codex automatically. See MCP setup for manual steps.
1. Give Terminal permission to read your messages:
System Settings → Privacy & Security → Full Disk Access → enable Terminal
2. Install:
brew tap DecisionNerd/tap
brew install imessage-analysis3. Run your first sync from Apple Terminal.app (not iTerm2 or other terminals — macOS needs this to ask for Contacts permission the first time):
imessage-analysis sync4. Start exploring:
imessage-analysis status
imessage-analysis top-contacts --limit 10
imessage-analysis time-series --year 2024
imessage-analysis reactions --received
imessage-analysis search-contacts alice
imessage-analysis query "SELECT year, COUNT(*) AS n FROM messages GROUP BY year ORDER BY year"Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"imessage": { "command": "imessage-mcp" }
}
}pip install imessage-analysisimport imessage_analysis
df = imessage_analysis.top_contacts().to_pandas()
df = imessage_analysis.query("SELECT * FROM messages WHERE year = 2024").to_pandas()Note:
imessage_analysis.sync()picks up new messages but won't resolve contact names — that requires runningimessage-analysis syncfrom the terminal at least once.
| Method | Command |
|---|---|
| Homebrew | brew tap DecisionNerd/tap && brew install imessage-analysis |
| Cargo | cargo install --git https://github.com/DecisionNerd/imessage-analysis |
| PyPI | pip install imessage-analysis |
| Claude Code / Codex / Cursor | npx skills add DecisionNerd/imessage-analysis |
Requires macOS. Rust 1.70+ for source builds. Python 3.11+ for the Python package.
| Installation | Full Disk Access, Homebrew, source, Python |
| CLI reference | All commands and flags |
| AI agent setup | Connecting to Claude, Codex, Cursor, ChatGPT |
| Python package | API reference, notebook examples |
| Data model | All 22 output columns |
| Contact resolution | Contacts.app + TOML overrides |
| Architecture | How it works under the hood |
| Releasing | Tagging, Homebrew formula update |
- Fork the repo and create a branch
cargo test --all— all tests must passcargo clippy -- -D warningsandcargo fmt- Open a pull request — CI runs automatically
This project uses Conventional Commits.
Inspired by the foundational work of Yorgos Askalidis, who first documented how to access and analyse the macOS iMessage database. See his original Python implementation and write-ups:
This is a separate, ground-up Rust rewrite that extends the concept with a native CLI, AI agent integration, and Python bindings.
Copyright (C) 2026 David Spencer. Released under the GNU General Public License v3.0.