wa — safe WhatsApp automation

wa

Personal WhatsApp automation CLI + daemon, written in Go.

A hexagonal Go daemon that owns a WhatsApp Multi-Device session and a thin JSON-RPC client that talks to it — safe enough to let a language model send messages on your behalf, crash-safe enough to survive a power loss mid-migration, and paranoid enough to refuse every destructive flag you might expect.

Quickstart · Install · Manual · Architecture · Security · Contributing · Português (BR)

---

Capability

Pattern. Persistent WhatsApp daemon over a Unix socket — one wad process holds the Multi-Device session, ratchet store, and websocket; a thin wa JSON-RPC client invokes it.

Trade-off. ~30 MB RSS per profile and a 5–8 s cold connect, in exchange for sub-second warm-call latency on every subsequent wa send. Per-call session reattachment is avoided entirely.

Use when. A shell pipeline, cron job, or Claude Code plugin needs to dispatch WhatsApp messages with predictable latency and a non-overridable safety pipeline (default-deny allowlist + rate limiter + warmup ramp + append-only audit log) sitting below every RPC path.

brew install yolo-labz/tap/wa

wad & # daemon, single instance per profile wa pair # QR-code pairing on first run wa allow add 5511999999999@s.whatsapp.net --actions send wa send --to 5511999999999@s.whatsapp.net --body "hello"

Demo

Every frame is real output from the binaries in this repo, recorded against a throwaway unpaired daemon in a private temp directory. doctor honestly warns that the device is unpaired (and may flag missing backups in the fresh sandbox). No real account data is used. The revoke command is help only, not a mutation.

The recording is generated, never hand-edited. The source of truth is the plain-text docs/assets/wa-demo.tape; regenerate the GIF, MP4, WebM, static PNG and captured text with one command:

nix develop -c ./scripts/record-demo.sh

Prefer playback controls or reduced motion? Use MP4, WebM, the static frame, or the text equivalent. Recording notes cover isolation, safety controls, byte budgets and checks. Playback is 1× and silent; no live sends are demonstrated.

How wa compares

Closest peers in the reverse-engineered-WhatsApp ecosystem:

For multi-tenant REST gateways see EvolutionAPI or WAHA — different shape of problem, listed in What this is NOT.

What this is

Two binaries, one repo:

• `wad` — long-running daemon that owns the WhatsApp session, the SQLite ratchet store, and the websocket to web.whatsapp.com. Runs under systemd (Linux), launchd (macOS), or a NixOS module. Single-instance per profile, never as root.
• `wa` — thin JSON-RPC client that speaks to wad over a unix socket. This is what shell scripts, cron jobs, and Claude Code plugins actually invoke.

It is built on go.mau.fi/whatsmeow — the library that powers mautrix-whatsapp at production scale — because it is the only reverse-engineered WhatsApp library actively maintained in 2026. It also ships a safety-first MCP server (wa mcp serve) so an AI agent drives WhatsApp through the same non-bypassable safety pipeline — draft-gated by default. See MCP server.

What this is NOT

• Not a bulk-messaging tool. The rate limiter is non-overridable and there is no --force flag anywhere.
• Not a multi-tenant SaaS. Each wa install is scoped to one person, with optional multi-profile isolation for work/personal splits.
• Not a Matrix bridge. Use mautrix-whatsapp if that's what you want.
• Not a REST gateway. Use EvolutionAPI or WAHA if that's what you want.
• Not the official WhatsApp Cloud API. This project uses the reverse-engineered Multi-Device protocol via whatsmeow.

Quickstart

# Install (Homebrew — macOS + Linuxbrew)

brew install yolo-labz/tap/wa

Or via Nix (recommended for NixOS/nix-darwin users)

nix profile install github:yolo-labz/wa

Or the checksum-verified installer (80 lines — inspect first if you like)

curl -fsSL https://raw.githubusercontent.com/yolo-labz/wa/main/install.sh | bash

Or Docker — single distroless container (~12 MB); /data holds the session

docker compose up -d # see docker-compose.yaml; pair via docker compose exec

Start the daemon (default profile)

wad &

Pair your phone — QR code in terminal

wa pair

Allowlist yourself (default-deny policy)

wa allow add 5511999999999@s.whatsapp.net --actions send

Send a message

wa send --to 5511999999999@s.whatsapp.net --body "hello from wa"

Install as a persistent system service

wad install-service --profile default

Hand it to an AI agent — MCP over stdio, draft-gated sends by default:

the agent PROPOSES messages into a human-review queue; nothing leaves

until you run wa draft approve. Add to Claude Desktop/Code, Cursor:

{"mcpServers": {"wa": {"command": "wa", "args": ["mcp", "serve"]}}}

wa mcp serve --help

The recipient flag is spelled --to, --jid, or --group depending on the command; --chat is accepted as a universal alias on all of them (the original flags still work).

For the full tour including multi-profile setup, shell completion, migration, and the audit log, see [`docs/manual.md`](./docs/manual.md).

MCP server

wa mcp serve exposes the daemon to AI agents over the Model Context Protocol (stdio transport). Every tool call runs through the same non-bypassable safety pipeline as the CLI — default-deny allowlist, enforced short-window limits (2/second with burst 2; 30/minute with burst 30; no daily ordinary-send cap) with warmup, and an append-only audit log. Sends default to draft mode: the model proposes a message into a human-review queue and nothing leaves until you run wa draft approve. That draft-gate is the point — it is what makes handing WhatsApp to an autonomous agent safe.

Live on the official MCP Registry as `io.github.yolo-labz/wa`; one-click install via the signed .mcpb bundle on each release, or wire it manually into Claude Desktop/Code or Cursor:

{ "mcpServers": { "wa": { "command": "wa", "args": ["mcp", "serve"] } } }

Tools (12):

It also serves resources (read-only context surfaces) and prompts (pre-built workflows) per the MCP spec. Scope the surface with --toolsets; the send mode is draft (default), direct, or deny, and a read-only set hides every mutating tool.

See [`docs/mcp-registry.md`](./docs/mcp-registry.md) for the registry publish flow and bundle internals.

Install

Homebrew (macOS + Linux)

brew install yolo-labz/tap/wa

Nix flake

# One-shot

nix run github:yolo-labz/wa -- profile list

Install to profile

nix profile install github:yolo-labz/wa

Dev shell (go + gopls + golangci-lint + goreleaser + sqlite + jq)

nix develop github:yolo-labz/wa

NixOS module — import the system module and enable:

{

inputs.wa.url = "github:yolo-labz/wa"; outputs = { self, nixpkgs, wa, ... }: { nixosConfigurations.myhost = nixpkgs.lib.nixosSystem { modules = [ wa.nixosModules.default { services.wa.enable = true; services.wa.profile = "default"; } ]; }; }; }

home-manager module — import for a per-user installation:

{

imports = [ wa.homeManagerModules.default ]; services.wa = { enable = true; profile = "default"; autoStart = true; }; }

GoReleaser tarball + supply-chain verification

VERSION=v2.0.5                                      # pin to a known tag

ARCH=linux_amd64 # or darwin_arm64 / linux_arm64 BASE="https://github.com/yolo-labz/wa/releases/download/$VERSION"

1. Download the tarball + checksums

curl -LO "$BASE/wa_${VERSION#v}_${ARCH}.tar.gz" curl -LO "$BASE/checksums.txt"

2. Veri