WireCat WhatsApp

wa — WhatsApp CLI for AI agents

Your personal WhatsApp in the terminal, searchable on your computer, and ready for Claude Code, Codex, Cursor or any agent — within limits you set.

Docs · Examples · WireCat

An example conversation (invented people, illustrative output):

You:    Use wa CLI. Who is waiting for my answer since yesterday?

Agent: (runs wa personal review 'date>1d' --unanswered: 3 chats) · Alice Example asked about Saturday's table, 18:40 yesterday · "Book club" — Bob Sample asked who brings the next book You: Tell Alice: yes, 8 pm. Agent: Draft to Alice Example: "Yes, 8 pm." Send it? You: Yes.

⚠️ `wa` is an unofficial client of your real WhatsApp account. WhatsApp's terms forbid unofficial clients, and

WhatsApp may ban an account that uses one. It also bans accounts that send in bulk or write to people who do not

know them. wa writes only when a command asks, sends at most 30 messages an hour by default, and holds every

write when WhatsApp says to slow down or restricts the account. Do not send in bulk, and do not write to strangers.

You use wa at your own risk. More: limits

Early. wa is new, and some of what it does has not yet been checked against real WhatsApp. The backlog lists the checks still to run.

More: compared with other tools · on wirecat.dev

Quick start

npm install -g @wirecat/whatsapp-cli

wa personal setup --agent claude # also codex, cursor, gemini, all or none wa personal server install # keep receiving in the background wa personal inbox # other people's unread messages; nothing is marked read

Allow about five minutes. wa personal setup links wa to your account as a device — you scan a QR code in WhatsApp → Settings → Linked devices — keeps the history your phone sends right after linking, checks your first chats and installs the agent skill.

It needs Node 22.16+ or 24+ on macOS, Linux or Windows. npm also installs the engine, the small program that speaks WhatsApp's protocol, as a separate package for your system.

More: installation guide · linking

What can you do?

Catch up. *"Use wa CLI. What came in since this morning, and who is waiting for my answer?"*

wa personal inbox

wa personal review 'date>1d' --unanswered

Find anything. *"Use wa CLI. When did we agree on the venue with Alice?"* — an answer with the date and the message itself.

wa personal search all "venue"            # messages and notes kept on this computer

Keep your promises. *"Use wa CLI. What did I promise, and what am I still waiting on?"*

wa personal review --new                  # what changed since the last review --new

wa personal tasks list state:open

Run your groups. *"Use wa CLI. Which questions in Hiking has nobody answered?"*

wa personal review chat:Hiking --unanswered

wa personal chats events Hiking 'time>=7d' # who joined, left, was added or removed

Answer, when you say so.

wa personal messages send "Book club" "Call at 3?" --reply-to 3EB0A1B2C3D4E5F6A7B8

wa personal messages edit "Book club" 3EB0A1B2C3D4E5F6A7B8 "Call at 4?" # your own, within 20 minutes wa personal reactions add "Book club" 3EB0A1B2C3D4E5F6A7B8 👍 wa personal messages delete "Book club" 3EB0A1B2C3D4E5F6A7B8 --for-everyone wa personal chats mark-read "Book club" # the other side sees it

More: recipes, with a schedule for each · using wa

Built for AI agents

Your agent. Your WhatsApp. Your rules.

• Agents with a terminal (Claude Code, Codex, Gemini CLI) run wa commands themselves. The bundled skill tells them how: wa personal setup --agent … or wa skill install puts it in place, and wa skill show prints it before linking. An agent links by QR: it pastes the code into the chat as text for you to scan, and never asks for your phone number or a code.
• Apps without a terminal (Claude Desktop, Cursor and other MCP clients) connect to wa personal mcp serve. It comes with ready prompts: /catch-up, /review, /reply, /find and more.

wa personal mcp add claude-code   # or: wa personal mcp add codex

wa personal mcp config # the entry for Claude Desktop, Cursor and others

The profile can send by default, so mcp add stops first. Check the profile's permissions, then run it again with --allow-writes.

More: the MCP server · from the browser

Why wa?

• Your own account, as a linked device. wa links the way WhatsApp Web does. It sees your chats, groups and contacts, and speaks as you, not as a business account or a bot.
• A business number too, when you have one. wa bot speaks for a WhatsApp Business number on Meta's Cloud API: send, templates, and messages received by webhook through your tunnel (bot).
• Local-first search. Everything received is kept on your computer. Every read and search answers from there and never connects.
• Made for agents. One operation per call, the same JSON shape every time with --json, a fixed exit code for each kind of failure, an MCP server and a skill.
• Safe by default. Reading marks nothing read and sends no "online" or "typing". A profile decides which actions an agent may take, which chats it may send to, and how many messages an hour (30 by default). When a send's outcome is unknown, wa says so and never repeats it by itself.

Your account

wa works in your name, as one more linked device of your WhatsApp account.

wa personal chats list --limit 5

wa personal messages list "Book club" --limit 20 wa personal messages send "Book club" "The minutes" --file minutes.pdf wa personal polls create "Book club" "Which day?" Monday Tuesday wa personal messages download "Book club" 3EB0A1B2C3D4E5F6A7B8 --output-dir ~/Downloads wa personal messages transcribe "Book club" 3EB0A1B2C3D4E5F6A7B8 --local # a voice note as text

The message id 3EB0A1B2C3D4E5F6A7B8 is made up; take a real one from messages list -v.

• Read. Chats and messages from the local store, one message with its neighbours, other people's unread messages (wa personal inbox), everything since the last review (wa personal review), new messages as they arrive (wa personal watch), older messages of one chat asked of your phone (wa personal messages sync), and the posts of the channels you follow (wa personal chats join with a channel link, then messages sync).
• Write. Markdown, replies, one file, photo, video or voice note per message, a photo and a video as one album, edits of your own messages within 20 minutes, forwards, reactions, polls and votes, pins (each one tells the members), deleting for you or for everyone, and marking a chat read.
• Your chat list. Mute, archive, pin or mark a chat unread, star a message, and delete or clear a chat on your own devices; nobody in the chat is told.
• Voice on your computer. WhatsApp has no speech recognition of its own, so wa runs a speech model on this machine, downloaded only when you ask.
• People. A person's profile, blocking, whether a number has WhatsApp, the phone's address book into the store, and your own names and notes for people.
• Your account. Your own name, about line and profile photo (wa personal account update).
• Privacy. Who sees your last seen, online, profile photo and about line, whether you send read receipts, who may add you to groups and whose calls ring (wa personal account privacy).

More files in one message than a photo and a video are not built yet: not in wa yet.

More: using wa · privacy · one person

Log in and profiles

wa links to your account as a device, the way WhatsApp Web does. There is no password and no app to register: you link once, from the phone, and the device keys go to one file only your user can read.

wa personal session start               # a QR code: WhatsApp → Settings → Linked devices → Link a device

wa personal session start phone # or your number, then a pairing code you type on the phone wa personal account show # who this profile is linked as wa account list # every profile here, and who each is linked as wa personal session end # unlink, and delete the device keys here

Several accounts are several profiles, and the profile is the first word, not an option:

wa personal chats list     # profile "personal"

wa work chats list # profile "work" export WA_PROFILE=work # or for the whole shell session

wa never picks a profile for you, not even the only one: a command that uses an account and has no profile named stops and lists the profiles on this computer. Name one or set WA_PROFILE. Each profile is a linked device of its own, with its own one connection.

More: linking, devices and profiles · profiles

The local store and search

Everything wa receives is kept in a local store on your computer, shared with tg and max. Search runs over it; nothing leaves your computer.

wa personal search messages 'contract chat:"Project Alpha"'

wa personal store status # how much of each chat is kept wa personal store export "Project Alpha" --format markdown --output alpha.md wa personal messages evidence "Project Alpha" --json # bounded evidence