WhatsApp Claude Plugin

WhatsApp Channel for Claude Code

Drive your Claude Code session from WhatsApp — your personal number, no bots, no API keys.

The plugin connects to WhatsApp as a linked device (the same protocol as WhatsApp Web, via Baileys) and exposes it to Claude Code as an MCP channel. Incoming messages reach your session in real time; Claude replies from your own number, so recipients see a normal chat. Everything runs locally on your machine — messages travel directly between WhatsApp and your session, with no third-party servers in between. Once paired, it keeps working while your phone is off; only the Claude Code session needs to stay open, and reconnects never require re-pairing.

Published on the Anthropic Official Plugin Marketplace — the first community-built WhatsApp channel plugin reviewed and published by Anthropic.

Installation

claude plugin marketplace add Rich627/whatsapp-claude-plugin
claude plugin install whatsapp-claude-channel@whatsapp-claude-plugin
claude --dangerously-load-development-channels plugin:whatsapp-claude-channel@whatsapp-claude-plugin

The --dangerously-load-development-channels flag matters: it registers the plugin as a channel, so an inbound WhatsApp message wakes your session immediately. Without it the tools still load, but nothing wakes the session when messages arrive — they sit unanswered until you (or a watchdog) prompt Claude to check. --channels does not accept this plugin yet (it is not on the research-preview allowlist), so the development flag is currently the only way.

Inside the session, set your number and pair:

/whatsapp-claude-channel:configure <phone>   # country code + number, no +

A pairing code is printed on first launch. On your phone: WhatsApp → Settings → Linked Devices → Link a Device → Link with phone number instead → enter the code. No WhatsApp Business API, Meta developer account, or API key is involved — it links to your regular account.

Features

• Bidirectional messaging. Send and receive from the session; long replies are chunked to WhatsApp's limits or sent as a document attachment past a configurable threshold.
• @-mentions. reply can tag people so they actually get notified — ids are accepted as phone, LID, or full JID, and mentions attach only to the chunk that names them.
• Full media support. Photos, voice notes, video, documents, and stickers, in both directions.
• Voice transcription. Incoming voice notes are transcribed locally via mlx-whisper (see setup); without the script they arrive as plain attachments.
• Access control. Pairing codes, allowlists, and per-group policies gate every inbound message — strangers never reach your session. Managed via /whatsapp-claude-channel:access.
• Per-group personalities. Each group gets its own config.md with a custom personality and conversation memory.
• Permission relay. Approve or deny Claude's tool requests from WhatsApp with an emoji reaction (👍 / 👎).
• Cron tasks. A ## Cron Jobs section in a group's config.md schedules recurring server-side tasks.
• Context recovery. After a restart, the catch_up tool replays recent two-way conversation per chat, unreplied counts, and open tasks from tasks.md, so a fresh session resumes mid-flight work.
• Dual accounts. Run personal and business numbers side by side with separate state and behaviors.
• Self-diagnosis. /whatsapp-claude-channel:doctor checks the server process, device link, singleton lock, and config, then walks you through the fixes — no more guessing why replies stopped.

How it works

WhatsApp (phone) <──Baileys──> MCP Server <──stdio──> Claude Code

The server (a single Bun process) holds the linked-device connection and forwards inbound messages to the session as channel notifications after they pass the access gate. Claude acts through MCP tools — reply, react, edit_message, download_attachment, status, unreplied, catch_up, list_groups. Runtime state (auth, allowlists, group configs, inbox) lives in ~/.whatsapp-channel/, never in the repo.

Messages sent by Claude appear as coming from your phone number. Use a dedicated number if you want a distinct bot identity.

Voice transcription (optional)

One-time setup (Apple Silicon, mlx-whisper):

brew install ffmpeg                      # mlx-whisper uses it to decode audio
python3 -m venv ~/whisper-env
source ~/whisper-env/bin/activate
pip install mlx-whisper
cp scripts/whisper-transcribe.sh ~/whisper-transcribe.sh
chmod +x ~/whisper-transcribe.sh
~/whisper-transcribe.sh path/to/sample.ogg   # optional: test

The reference script uses mlx-community/whisper-large-v3-turbo — accurate, fast, multilingual. Swap the model in the script if you prefer a smaller one.

Troubleshooting

Issue	Solution
Pairing code not showing	Run /whatsapp-claude-channel:configure <phone> first, then relaunch
440 disconnect error	Only one connection per auth state allowed. Kill stale processes: pkill -f "whatsapp.*server"
Session not waking on new messages	Most common cause: launched without --dangerously-load-development-channels plugin:whatsapp-claude-channel@whatsapp-claude-plugin. Tools work but inbound pushes are dropped (Channel notifications skipped in the MCP debug log) — relaunch with the flag.
Messages not arriving	Known Claude Code client bug (#37933). Server-side is correct, awaiting client fix.
Auth expired	Run /whatsapp-claude-channel:configure reset-auth and re-pair

Documentation

Full documentation lives in USAGE.md: access control, the tools exposed to the assistant, dual-account setup, session conflicts, and resetting auth.

Contributing

Issues and pull requests are welcome — read CONTRIBUTING.md before opening one. Report security issues privately per SECURITY.md.

Star History

License

Apache 2.0 — Copyright 2025 Richie Liu