steipete/whatsapp

WhatsApp

Use this as the first stop for WhatsApp work. Keep the source boundary sharp:

• wacrawl: primary WhatsApp Desktop archive. Read-only, best local history, no network, no sending.
• wacli: linked-device accounts. Use for alt accounts, live sync, auth, sending, chat/group mutation, and WhatsApp Web protocol questions.

If the user names wacrawl or wacli repo work specifically, read that tool's own skill too.

Routing

• Primary WhatsApp reads/search/history: use wacrawl.
• Read/unread counts from WhatsApp Desktop: use wacrawl; it has chat-level unread counts, not per-message read state.
• Freshness-sensitive primary reads: check wacrawl status; run wacrawl sync when asked or when current data matters.
• Alt accounts such as me, molty, or named stores: use wacli --account NAME.
• Sending, reactions, presence, archive/pin/mute/mark-read, group/channel mutations: use wacli only after explicit user intent.
• Comparing coverage between sources: treat wacrawl as Desktop archive truth for primary history, and wacli as linked-device/live coverage with protocol limits.

Safety

• Never send or mutate WhatsApp state unless explicitly requested.
• Prefer read-only wacli commands for inspection: pass --read-only or set WACLI_READONLY=1.
• Do not write into WhatsApp Desktop's app container.
• Do not edit wacli session.db directly.
• Keep named wacli accounts isolated; do not merge stores.
• Report source freshness, account name, and known gaps when answering from local stores.

Common Commands

Primary Archive

Freshness and status:

wacrawl status
wacrawl doctor
wacrawl sync

Unread triage:

wacrawl chats --limit 20
wacrawl unread --limit 20
wacrawl --json unread --limit 100

Search and slice messages:

wacrawl messages --after 2026-01-01 --limit 50
wacrawl messages --chat JID --asc --limit 100
wacrawl messages --has-media --limit 50
wacrawl --json search "query"
wacrawl search "query" --after 2026-01-01 --from-them

Archive media or backups, only when asked:

wacrawl import --copy-media
wacrawl backup status
wacrawl --sync never backup push

Alt/Live Accounts

Account discovery and read-only inspection:

wacli accounts list --json
wacli --account me auth status --read-only --json
wacli --account me chats list --read-only --json
wacli --account me messages list --read-only --json --limit 50
wacli --account me messages search --read-only --json "query"

Background live sync, only when requested. Prefer tmux for follow-mode:

wacli --account me sync --follow --events
wacli --account me sync --once --events

Media, sending, and live mutations, only when explicitly requested:

wacli --account me media download --chat JID --id MESSAGE_ID
wacli --account me send text --to JID_OR_NAME --message "message"
wacli --account me send file --to JID_OR_NAME --file ./file.jpg --caption "caption"
wacli --account me send text --to JID --reply-to MESSAGE_ID --message "reply"

Comparisons

When comparing wacrawl and wacli, compare both counts and overlap:

• message counts and date spans
• chat counts
• newest message timestamp
• overlap by msg_id
• overlap by chat_jid + msg_id when JIDs are normalized enough
• obvious gaps explained by linked-device history limits vs Desktop archive coverage

Repo Pointers

• ~/Projects/wacrawl: Desktop archive importer/search/backup.
• ~/Projects/wacli: linked-device client/sync/send.
• Global skill copies: ~/Projects/agent-scripts/skills/wacrawl and ~/Projects/agent-scripts/skills/wacli.