wacrawl 🧾 — WhatsApp archaeology with encrypted receipts

wacrawl makes a read-only snapshot of the macOS WhatsApp Desktop databases and imports chats, contacts, messages, and media metadata into a local SQLite archive. It is for people who want fast local search, structured exports, a private web viewer, or encrypted Git backups without connecting to WhatsApp's network protocol.

Install

On macOS, v0.3.10 and newer require macOS 13 or newer. v0.3.9 remains the last release supporting macOS 12.

Homebrew is the smallest path:

brew install openclaw/tap/wacrawl

Upgrade later with brew upgrade openclaw/tap/wacrawl.

Or install from source with Go 1.27.0 or newer:

go install github.com/openclaw/wacrawl/cmd/wacrawl@latest

Source builds with Go 1.27 also require macOS 13 or newer.

Direct source discovery requires macOS and the desktop WhatsApp app. Release builds for macOS, Linux, and Windows can work with an existing archive or encrypted backup.

Quick start

Check the source, import it, then inspect the archive:

wacrawl doctor
wacrawl sync
wacrawl status
wacrawl search "invoice"

Read commands refresh a stale archive when the WhatsApp source is newer. To browse instead:

wacrawl web

The viewer prints a private local URL, binds only to 127.0.0.1, and stops with Ctrl-C.

What it reads

WhatsApp Desktop keeps its macOS data under:

~/Library/Group Containers/group.net.whatsapp.WhatsApp.shared

wacrawl snapshots ChatStorage.sqlite, ContactsV2.sqlite, and their SQLite sidecars before reading. With --copy-media, it also copies referenced files from Message/Media/. Its own archive defaults to ~/.wacrawl/wacrawl.db.

Imports merge by stable source identity, retain older history that has disappeared from the current desktop snapshot, and preserve explicit edits and deletions as revisions or tombstones. Use a separate --db for another WhatsApp account; source adoption and exact restore are deliberate operations described in the command reference.

Search and automation

Search covers message text, chat and sender names, and media titles:

wacrawl search "release notes" --from-them --after 2026-01-01
wacrawl messages --chat 1234567890@s.whatsapp.net --has-media
wacrawl sql "SELECT count(*) FROM messages"

Add --json for scripts and agents:

wacrawl --json --sync never search "invoice"
wacrawl --json --sync never contacts export

See the command reference for filters, sync modes, SQL constraints, and every subcommand.

Running imports on a launchd or cron schedule? macOS prompts "would like to access data from other apps" on every background run, and Allow does not persist. The scheduled imports guide covers the Full Disk Access setup that makes unattended imports work.

Encrypted backups

wacrawl backup exports deterministic JSONL shards, compresses them, and encrypts them to one or more X25519 age recipients before Git sees the data. Copied media can travel in content-deduplicated encrypted blobs, and restores verify hashes and cross-table references before replacing the archive.

wacrawl backup init --repo ~/Projects/backup-wacrawl --remote <git-url>
wacrawl backup push
wacrawl backup snapshots
wacrawl backup pull

The manifest remains cleartext and reveals backup timing, public recipients, counts, shard paths, encrypted sizes, and hashes. Read the backup guide and threat model before relying on it for recovery.

Safety boundary

• The WhatsApp databases are opened read-only through a temporary SQLite snapshot.
• Normal archive and search commands do not upload data or write into WhatsApp's app container.
• The web viewer is loopback-only, read-only, protected by a random per-run access key, and restricts media reads to known roots.
• backup push is the explicit networked path; it sends age-encrypted shards to the configured Git remote.

The archive still contains private message data in plaintext. Keep ~/.wacrawl/wacrawl.db and copied media out of commits, shared logs, and untrusted backups unless sharing them is intentional.

Commands

Run wacrawl help <command> or open the full command reference.

Documentation

• Commands, filters, paths, and sync behavior
• Scheduled imports on macOS and the TCC prompt loop
• Encrypted backups, recovery, and threat model
• Archive identities and data model
• Release process

Development

Requires Go 1.27.0 or newer.

The preferred build toolchain is Go 1.27.1, selected automatically by go.mod and CI. The source minimum remains Go 1.27.0.

Keep modernc.org/libc at the exact version required by modernc.org/sqlite; SQLite's generated code depends on that runtime pairing. Update them together, and check test-only compiler updates for indirect libc upgrades. make deps and CI verify the resolved versions.

make build
make test
make check

Use the GoReleaser version pinned in CI for local snapshots.

make check mirrors the local CI gates: formatting, analysis, tests, race and coverage checks, dependency and vulnerability checks, a credential-free GoReleaser snapshot, release-script tests, and secret scans.

License

MIT. See LICENSE.