How to use the wacli WhatsApp agent skill: setup and examples

What an agent skill is and what wacli lets the agent do

An agent skill is a folder containing a SKILL.md file with instructions that an AI agent reads when a task matches the skill. This one is named wacli and is described as sending WhatsApp messages to other people or searching and syncing WhatsApp history through the wacli CLI.

Once installed and linked, the agent can send text messages, group messages and files to contacts when you explicitly ask. It can also list chats, search messages, including by date range, and backfill history for a chat.

• Send a text, group message or file to a named recipient or number
• Search messages by keyword, chat, or date range such as an invoice in 2025
• List chats to find the right contact or group ID
• Back up or backfill older messages for a chat

Install the wacli skill

Download the skill ZIP from this page and unzip it. The skill folder contains SKILL.md. Place the unzipped folder in ~/.claude/skills/ for your user account, or in a project's .claude/skills/ folder to limit it to that project.

Alternatively, in the Claude apps, open Settings, then Capabilities, then Skills, and upload the skill there.

The skill itself does not include the wacli tool. You must install wacli separately. The skill metadata lists two options: Homebrew, using the formula steipete/tap/wacli, or the Go toolchain, using github.com/steipete/wacli/cmd/wacli@latest.

• Option A: Homebrew, formula steipete/tap/wacli
• Option B: Go, module github.com/steipete/wacli/cmd/wacli@latest

Link your WhatsApp account and sync

Run the auth command to log in by scanning a QR code with your WhatsApp account. It also performs an initial sync. To keep syncing continuously, use the follow option on sync. Run doctor to check the setup.

Store data is kept in ~/.wacli by default. You can point it elsewhere with the --store option.

• wacli auth: QR login and initial sync
• wacli sync --follow: continuous sync
• wacli doctor: health check

Ask the agent in plain language

You do not need to type commands yourself. Ask the agent directly and name the recipient and the message. The skill requires an explicit recipient and message text, and the agent should confirm both before sending. If your request is vague, the agent should ask a clarifying question instead of guessing.

Good requests name a person or group, give the exact wording, and say whether to send now. For searches, name the keyword and a time window or chat if you have one.

Messages to your own WhatsApp chat with the agent are not meant to use this tool. The skill says to leave ordinary chats alone unless you ask it to contact a third party.

• Send to a contact: "Message +14155551212 saying I am running 5 minutes late. Confirm before sending."
• Search: "Find invoice messages from 2025 in my WhatsApp history."
• Send a file: "Send /path/agenda.pdf to +14155551212 with the caption Agenda."

Command examples from the skill

These are the commands the skill documents. Replace the numbers, JIDs and paths with your own. Use --json when output needs to be parsed by another program.

Direct chats use the form <number>@s.whatsapp.net and groups use <id>@g.us. Run wacli chats list to find the correct identifier.

• Search one chat with --chat <jid>
• Backfill with --requests and --count to control how much history is fetched

Safety, privacy and network notes

This skill runs scripts and uses the network. The wacli tool reads and stores your message history locally, and the agent may access that history when searching. Treat it as access to your WhatsApp account.

Do not use it for automated or bulk messaging. Sending messages people did not request risks WhatsApp account restrictions. Backfill needs your phone to be online, and results are best-effort, so a search may not return everything.

• Only give the agent recipients and text you actually want sent
• Review the confirmation the agent shows before it sends
• Avoid use with sensitive private conversations
• Remove or revoke access if you no longer want the tool to hold your account

Tips for reliable results

Run wacli chats list before sending to a group, so you use the correct group identifier. Use keyword and date filters to keep searches small. If a backfill returns less than you expected, check that your phone is online and try again.

• Use the exact JID from chats list for groups
• Narrow searches with --after, --before and --chat
• Use --json when a script will read the output