WireCat WhatsApp

[WhatsApp CLI for AI agents]

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

[npm] [CI] [Node] [Bun] [npm downloads] [License: Apache 2.0]

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 bookYou:    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-cliwa personal setup --agent claude       # also codex, cursor, gemini, all or nonewa personal server install             # keep receiving in the backgroundwa 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 inboxwa 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 --newwa personal tasks list state:open

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

wa personal review chat:Hiking --unansweredwa 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 3EB0A1B2C3D4E5F6A7B8wa personal messages edit "Book club" 3EB0A1B2C3D4E5F6A7B8 "Call at 4?"   # your own, within 20 minuteswa personal reactions add "Book club" 3EB0A1B2C3D4E5F6A7B8 👍wa personal messages delete "Book club" 3EB0A1B2C3D4E5F6A7B8 --for-everyonewa 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 codexwa 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 <profile> 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 5wa personal messages list "Book club" --limit 20wa personal messages send "Book club" "The minutes" --file minutes.pdfwa personal polls create "Book club" "Which day?" Monday Tuesdaywa personal messages download "Book club" 3EB0A1B2C3D4E5F6A7B8 --output-dir ~/Downloadswa 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 devicewa personal session start phone         # or your number, then a pairing code you type on the phonewa personal account show                # who this profile is linked aswa account list                         # every profile here, and who each is linked aswa 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 keptwa personal store export "Project Alpha" --format markdown --output alpha.mdwa personal messages evidence "Project Alpha" --json   # bounded evidence for a chat briefwa personal store backup ~/wa-backup.db   # a copy, safe while the store is in use

More: search · the local store · query language

Groups you run

wa personal review chat:Hiking --unanswered          # questions nobody answeredwa personal review 'chat:Hiking date>7d'             # the week: decisions, promises, open questionswa personal chats events Hiking 'time>=7d'           # who joined, left, was added or removed, and by whomwa personal chats inspect https://chat.whatsapp.com/AAAAAAAAAAAAAAAAAAAAAA  # where an invite leads, without joiningwa personal stats chats show Hiking --offline        # the group's activity, from the local storewa personal chats create "Hiking 2027" 100000000000002@lid   # a new group, with people you knowwa personal chats members add [email protected] 100000000000002@lidwa personal chats update [email protected] --join-approval onwa personal chats requests list [email protected]

Renaming a group, its photo, members and admins, the invite link, join requests and who may send or add people are commands too. The members see each change, so each passes the profile's permissions and hourly limit. wa adds only people in your address book or that you have written to: WhatsApp bans accounts that add strangers.

More: groups

Agent setup in detail

The skill. Claude Code reads ~/.claude/skills/whatsapp-cli/; Codex and Gemini CLI read ~/.agents/skills/whatsapp-cli/. Start a new agent session if it does not see the skill.

wa skill install --for all        # both folders, without linkingwa skill show                     # the complete instructions, without installing them

The MCP server. The profile's permissions decide which tools it offers. readonly stops the agent from changing anything; at ask the server shows no form, so set up approval in your agent app.

claude mcp add wa -- wa personal mcp serve  # Claude Code, by handwa personal mcp check                       # check the local MCP server

From the browser. ChatGPT or Claude in the browser reach wa personal mcp serve --http --public-url behind your tunnel, after a login with a one-time access code from your terminal.

More: the MCP server · from the browser

Output for scripts and agents

With --json a command prints only data, as one JSON value. --jsonl prints one object per line. Every list has one shape:

{ "items": [ … ], "page": { "limit": 20, "has_more": true }, "meta": { … } }

An error goes to stderr as one line, with stdout empty, and the command exits with a fixed code: 4 link the profile, 5 the profile may not do this, 6 chat or message not found, 8 a limit, 12 another command holds the device, 14 unknown whether a message went. wa commands --json is the whole command tree.

More: CLI contract · every command and exit code

Settings and permissions

wa personal config set permissions.messages readonly   # no change to messages from this profilewa personal config set permissions.messages.send ask   # a question in the terminal before each sendwa personal config set sends_per_hour 10               # at most 10 sends an hour (30 by default)wa personal recipients add "Book club"                 # the first add turns the recipient list onwa personal sends list                                 # every attempt: sent, refused, failed or not knownwa personal config show                                # what is set, and where it came from

More: permissions · profiles · configuration · limits

Limits

Each profile has one request pace, shared by every command, serve and the MCP server at once, so a script stays far from what WhatsApp bans. A profile sends at most 30 messages an hour by default. One command at a time may connect a profile; another one is refused with exit code 12 and names the holder, unless serve runs and carries it on its connection. There is nothing to download in bulk: reads answer from the local store.

More: limits and waits

Security

• The device keys are one file readable only by your user. Whoever copies it can read and send as you until you remove the device on your phone. No command takes a phone number or a pairing code as an argument.
• The local store holds the full text of what was received, unencrypted and readable only by your user.
• Every send, from a command or over MCP, passes the profile's limits and is written to a journal — without its text.
• Nothing wa sends to WhatsApp names this tool: it links as a desktop browser.

To report a vulnerability: SECURITY.md. More: security

When something goes wrong

wa personal doctor          # the engine, the device keys' file modes and who holds the connectionwa personal doctor --online # also connect once and read the accountwa personal runs list       # recorded runs

More: troubleshooting by symptom · diagnostics

How it differs

wa shares its commands, its store and its agent tools with tg and max, so what you learn in one works in the others. WhatsApp is different in three ways:

• History comes from your phone. WhatsApp's servers keep no history to ask for. Your phone sends your recent chats once, when wa links, and wa serve keeps receiving new ones. Older messages of one chat can be asked of the phone, 50 at a time, while WhatsApp is open on it (wa personal messages sync). Every read answers from the local store and never connects.
• One connection per device. WhatsApp allows one. While wa serve runs, other commands for the same profile, a send included, run through its connection. On Windows they are refused until serve stops, for now.
• Unofficial. The risk of a ban is in the warning at the top of this page. wa never sends "online" or "typing", and marks nothing read unless you ask.

Part of WireCat

WireCat is an open-source, local-first context layer for AI agents. wa sits beside tg for Telegram and max for MAX, in the same local store.

Questions and setup help: join the WireCat Discord. Bugs go to this repository's issues.

Technical docs

Every page is in docs/:

What each version changed: CHANGELOG.md.

Development

pnpm installpnpm lint && pnpm typecheck && pnpm testpnpm engine:build && pnpm engine:test   # the Go engine; needs Gopnpm generate                           # rewrites docs/commands.md from the command treebin/wa personal chats list              # config, state and device under .wa/; a worktree's store too

Everything that is not specific to WhatsApp — the commands, the store, the send guard, the MCP server — lives in cli-core, shared with tg and max.

More: ARCHITECTURE · TESTING

Contributing

Pull requests, bug reports and ideas are welcome in issues.

Custom automation with WhatsApp, other messengers and AI agents: [email protected].

License

The CLI is Apache-2.0. The engine is not: the Go program in engine/ and the @wirecat/whatsapp-engine-* packages that carry it are GPL-3.0-only, because the engine links go.mau.fi/libsignal, which is under the GNU General Public License 3.0, through whatsmeow. The two are separate programs: wa starts the engine as a child process and talks to it only over stdin and stdout. Each engine package says where its source is and lists every Go module it links in THIRD_PARTY_NOTICES.