msg-summarizer 0.1.0

Local macOS app for browsing, summarizing, and chatting about your iMessage history. Private by default.

msg-summarizer

A local macOS app for browsing, summarizing, chatting about, and semantically searching your iMessage history. Reads chat.db read-only; your messages stay on your Mac.

pipx install msg-summarizer
msg-summarizer serve

…then open the browser tab it launches and add your Anthropic API key in the banner.

What it does

• Profiles for every conversation and every person, with per-month stats (message counts, who initiates, response latencies, active hours, top emojis) — no API calls, all local.
• Stored monthly summaries — backfill once, reuse forever. Each new month's summary gets prior months' summaries as context, so the long-history story stays consistent across years.
• Live-editable notes per contact that the model treats as ground truth — type "PIP = project plan, not a person" and the summary respects it.
• Semantic search with on-device embeddings (no embedding API calls either). Search by meaning: "trip planning", "feeling burned out", "what we said about the new car".
• Chat about a conversation — ask anything, draft replies, get advice. Range-scoped + retrieval-augmented, so questions about specific topics pull the relevant snippets, not just the most recent.
• People merging — Russell Chen's phone, iCloud email, and SMS handle collapse into one person via macOS Contacts. Group chats with no name are labelled by their participants in alphabetical order.

Privacy

• Reads, never writes ~/Library/Messages/chat.db.
• The semantic index, profile stats, monthly summaries, and notes all live in ~/.msg-summarizer/app.db on your Mac.
• Embeddings run on-device (fastembed, ONNX). No data leaves your machine for search.
• The Anthropic API receives only the specific text you ask to summarize or chat about — never your whole history, and never anything else.
• Contact names are pulled directly from the macOS AddressBook database on your Mac (covered by the same Full Disk Access permission), not from any network call.
• Your Anthropic API key is stored locally in ~/.msg-summarizer/.env with mode 0600.

Requirements

• macOS (tested on Sonoma+). iMessage's chat.db is Mac-only.
• Python 3.11+.
• Full Disk Access for the terminal/launcher you run msg-summarizer serve from. The app shows a step-by-step screen if it can't read chat.db.
• An Anthropic API key — get one at https://console.anthropic.com/. Summary and Chat use it; everything else works without.
• ~50 MB for the embedding model, downloaded the first time you build a semantic index.

Install

pipx gives the cleanest install (pip with an isolated env):

brew install pipx
pipx ensurepath
pipx install msg-summarizer

Or use pip in a venv:

python3 -m venv ~/.venvs/msg-summarizer
~/.venvs/msg-summarizer/bin/pip install msg-summarizer
~/.venvs/msg-summarizer/bin/msg-summarizer serve

Run

msg-summarizer serve

Opens the app at http://127.0.0.1:8765. The first time:

1. If Full Disk Access isn't granted, the app shows a step-by-step page — add your terminal app (Terminal / iTerm / Warp / VS Code / Cursor / whichever you ran serve from) to System Settings → Privacy & Security → Full Disk Access, quit and reopen it, then click Re-check.
2. Paste your Anthropic API key into the banner at the top of the app (or skip if you only want Profile / Search). It's saved to ~/.msg-summarizer/.env.
3. Click a chat or person in the sidebar. Profile loads instantly with stats. Use the tabs at the top to view messages, build the semantic index, generate a summary, or chat.

CLI features (without the UI)

The app also has direct commands:

msg-summarizer list-contacts          # show known handles + counts
msg-summarizer messages "Russell"     # dump a full thread as plain text
msg-summarizer summarize "Russell" --days 30
msg-summarizer chat "Russell"         # interactive chat in the terminal
msg-summarizer serve                  # launch the web UI

Pass --help to any command for more.

Costs

Summarize and Chat hit the Anthropic API; you pay your usual rate. The app paces requests under your tier's input-tokens-per-minute limit (30k on tier 1) so it can't spike your bill. All-time summarize on a heavy contact (hundreds of thousands of messages) is in the dollars-to-tens of dollars range and takes ~20 minutes; once stored, re-opening is free.

Stats, Search, the semantic index, message browsing, and Contact-name resolution cost zero dollars and zero network calls.

Development

git clone https://github.com/andrewjyuan/msg-summarizer
cd msg-summarizer
pip install -e .
cd frontend && npm install && npm run build && cd ..
msg-summarizer serve

The frontend is React + Vite (TypeScript). For UI development, run npm run dev in frontend/ alongside serve — Vite's dev server proxies /api to the backend.

License

MIT.