mcpField
W
whatsapp

whatsapp

github.com/steipeteProductivity7.4k88 installsUpdated 1d ago
Repository

About whatsapp

A workflow skill for handling WhatsApp tasks, routing archive searches to wacrawl and linked-device or live actions to wacli. It emphasizes read-only inspection and requires explicit intent before sending messages or changing account state.

Key features

  1. 01Routes archive searches to wacrawl
  2. 02Routes live accounts to wacli
  3. 03Checks sync freshness and unread chats
  4. 04Requires consent for sending or mutations

Use cases

  1. 01Search primary WhatsApp history
  2. 02Inspect alternate linked-device accounts
  3. 03Triage unread chats
  4. 04Compare archive and live message coverage

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/steipete/agent-scripts --skill whatsapp

After installing, type/whatsappin Claude Code to confirm it loaded.

Details

From the project README

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.

Comments

Markdown supported