Metadata-Version: 2.4
Name: msg-summarizer
Version: 0.1.1
Summary: Local macOS app for browsing, summarizing, and chatting about your iMessage history. Private by default.
Project-URL: Homepage, https://github.com/andrewjyuan/msg-summarizer
Project-URL: Repository, https://github.com/andrewjyuan/msg-summarizer
Project-URL: Issues, https://github.com/andrewjyuan/msg-summarizer/issues
Author: Andrew Yuan
License: MIT
License-File: LICENSE
Keywords: anthropic,claude,embeddings,imessage,macos,semantic-search,summarizer
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: anthropic>=0.52.0
Requires-Dist: click>=8.1
Requires-Dist: fastapi>=0.110
Requires-Dist: fastembed>=0.4
Requires-Dist: numpy>=1.26
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pytypedstream>=0.1.0
Requires-Dist: uvicorn>=0.29
Description-Content-Type: text/markdown

# 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.

```sh
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** — a contact's phone, iCloud email, and SMS handle
  collapse into one person via macOS Contacts (same Contact card → same
  person). 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](https://pipx.pypa.io/) gives the cleanest install (`pip` with an
isolated env):

```sh
brew install pipx
pipx ensurepath
pipx install msg-summarizer
```

Or use `pip` in a venv:

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

## Run

```sh
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:

```sh
msg-summarizer list-contacts             # show known handles + counts
msg-summarizer messages "+15551234567"   # dump a full thread as plain text
msg-summarizer summarize "+15551234567" --days 30
msg-summarizer chat "+15551234567"       # 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

```sh
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.
