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 temp directory — which is why doctor shows one honest WARN and no JID, phone number, or session data appears anywhere.

The recording is generated, never hand-edited. The source of truth is the plain-text docs/assets/wa-demo.tape; regenerate the GIF from a clean checkout with one command:

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

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 <jid> 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.

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):