whatsapp

name	whatsapp
description	Send WhatsApp messages, list chats, and search history via wacli (local CLI backed by a synced store at ~/.wacli). Use after the user has run `wacli auth` to pair the device.

WhatsApp (wacli)

Send messages, list chats, and search history using wacli — a local CLI that syncs a WhatsApp Web session into ~/.wacli/. No third-party service, no API key; the auth flow is a QR-code scan from the user's phone.

When to use

• The user asks to send a WhatsApp message, list chats, or search WhatsApp history.
• The user asks "did X message me on WhatsApp?" or similar history-search questions.
• Not available until wacli auth has completed on this Mac. Probe with wacli chats list --limit 1; if it errors "not authenticated," tell the user to run wacli auth (QR-code pairing from their phone).

Install + auth

brew install steipete/tap/wacli       # one-time install (3rd-party tap, NOT Homebrew-core)
wacli auth                            # opens a QR for the user to scan from WhatsApp → Linked Devices

steipete/tap is a third-party Homebrew tap (not Homebrew-core), and wacli stores a WhatsApp Web session locally at ~/.wacli/. Review the tap source before installing if security-sensitive.

The session lives at ~/.wacli/. Stays signed in across reboots until the user revokes the linked device from their phone.

Optional .env settings (label shown in WhatsApp's Linked Devices screen on the user's phone):

WACLI_DEVICE_LABEL=Sutando            # any string; appears next to the device in WhatsApp → Linked Devices
WACLI_DEVICE_PLATFORM=CHROME          # default per wacli is DESKTOP; CHROME is the fallback if an invalid value is set.
                                      # See wacli's docs (https://github.com/steipete/wacli) for the full platform-string list.

Commands

wacli send text --to "[phone]" --message "Hello!"     # send
wacli send text --to "[phone]" --message "$(cat draft.txt)"  # multi-line via stdin / file
wacli chats list --limit 20                                # recent chats
wacli messages search "keyword" --limit 10                 # search history
wacli messages list --chat "[phone]" --limit 20       # read a thread

Phone numbers are in E.164 (+countrycode...). For groups, pass the JID returned by wacli chats list instead of a phone number.

Conventions

• Always confirm message content with the user before sending. Matches the iMessage / SMS / X-post pattern in CLAUDE.md. The confirmation flow lives in the agent / bridge that calls wacli send — this skill itself has no confirm step. Treating the SKILL.md as the confirmation surface would skip the check entirely on direct CLI invocations.
• For multi-line / long messages, write to a /tmp/wa-*.txt and pass via --message "$(cat /tmp/wa-X.txt)" — avoids shell-escape issues with quotes and emoji.
• WhatsApp delivers messages best-effort; wacli send text returning success means the message hit WhatsApp's servers, not that the recipient has read it.

Failure modes

• wacli: not authenticated → user must run wacli auth (QR-code flow). One-time per Mac.
• wacli: linked device revoked → user revoked the session from their phone. Re-run wacli auth.
• wacli: rate limited → WhatsApp is throttling. Back off ~30s and retry.
• Phone-number invalid → confirm the user provided E.164 format with a + prefix.

Origin

Synthesizes the proposal in PR #180 by @priyansh4320 (stale + conflicts, never landed) and the wacli reference already documented in CLAUDE.md's "Built-in capabilities" section. Issue #179 (asking for WhatsApp support) was closed 2026-05-16 noting the capability had landed as inline doc.