---
name: whatsapp
description: On-demand, read-only read of the owner's local WhatsApp history (the native macOS WhatsApp app's store). Use when the owner asks "what did X send me on WhatsApp", "any WhatsApp messages I haven't replied to", "catch me up on the <group> chat", "read my WhatsApp since yesterday", or "did anyone WhatsApp me about …". The owner asks in plain language — never make them run a command. The agent runs the reader as plumbing and answers with a synthesized read (grouped by chat, newest first, flagging what needs a reply), then offers to open any chat in full. Read-only: it never sends, replies, or writes to the vault. Runs on the local machine where the WhatsApp Mac app is signed in, not an automation host, and needs macOS Full Disk Access. NOT iMessage/SMS (that's the imessage skill), NOT email/chat triage (attention-digest), NOT for sending messages. Requires the whatsapp module.
served: false
---

# WhatsApp — read my WhatsApp (on-demand, read-only)

The **inbound, WhatsApp** counterpart to the iMessage reader. The owner asks in
plain language; this skill reads their local WhatsApp history and hands back a
**useful synthesis** — never a raw command for the owner to run, and never a wall of
transcript unless they ask for one. The full procedure is canonical in
**[[WhatsApp]]** (`Agent/docs/WhatsApp.md`); this is the trigger.

## When this skill fires
The owner says, in chat, some form of *"what did X send me on WhatsApp / any
WhatsApps I owe a reply / catch me up on the <group> chat / read my WhatsApp since
yesterday / did anyone WhatsApp me about Z."* On-demand and owner-only — never
scheduled, never sent anywhere.

## What to do
1. **Read [[WhatsApp]]** (`Agent/docs/WhatsApp.md`) — it wins over anything remembered here.
2. **Scope the ask, then run the reader as plumbing** — `"${ALEXANDRIA_PYTHON:-python3}" -m alexandria_vault.engine.whatsapp_read --vault .`
   (prefer `--json`). Default to the last 24h across direct and group chats; narrow
   with `--from <person>`, `--thread <chat>`, `--direct-only`, or `--since 7d|today|<date>`
   when the owner names one. **`--thread` alone reads the whole chat** — add `--since`
   for a busy group. The owner never sees or types this command.
3. **Sanity-check the coverage line before synthesizing.** Every run prints one stderr
   line — `window <start> → N msgs / T chats · oldest <time>`; the `oldest` stamp must
   reach back to the window start. A `TRUNCATED` warning means a cap dropped older
   messages — re-run with `--limit 0` before answering.
4. **Answer with a synthesis, not a transcript.** Group by chat (direct chats first,
   then groups), newest first, and **lead with anything that needs the owner** — a
   direct question to them, an unanswered inbound, a request or deadline — then one
   tight line per chat (*who · gist · are they waiting on you*), linking people to
   their `People/` home. Busy groups get a one-line gist, not a replay. Offer to open
   any chat in full; show a raw transcript only when asked.

## Rules (detailed in [[WhatsApp]])
- **Prerequisite: Full Disk Access.** macOS blocks WhatsApp's group container until
  the app running the assistant (Claude, or its terminal) has Full Disk Access. It's a
  one-time System Settings grant, not a credential.
- **Needs the native Mac app.** The store is the App Store WhatsApp app's
  `ChatStorage.sqlite`; the old Electron "WhatsApp Desktop" has nothing readable.
- **Runs locally**, on the machine signed into WhatsApp — never on an automation host.
- **Read-only, full stop.** It never sends, replies, marks read, or writes (to WhatsApp
  or the vault). Sending is a separate, unbuilt capability — don't improvise one.
- **Media is a placeholder.** Images, voice notes, documents, stickers show as
  `[image: caption]`, `[voice note]`, `[document: name]` — the reader never exports files.
- **Names come from the store, then the maps.** WhatsApp carries the address-book
  partner name itself; the contacts module's shared handle map and this module's
  `contacts.json` (PII, gitignored) label what's left. Without them, raw numbers show.
