WhatsApp Channel for Claude Code
A custom Claude Code Channels plugin that adds WhatsApp as a messaging channel, using Baileys v7 (WhatsApp Web Multi-Device protocol).
Note: This is a personal project that I've open-sourced for the community. It works for my 24/7 setup and I'm sharing it as-is. PRs are welcome.
How it works
WhatsApp (phone)
↕ Baileys v7.0.0-rc.9 (Multi-Device protocol)
server.cjs (MCP server with channel + permission relay capabilities)
↕ notifications/claude/channel
Claude Code (receives and responds to WhatsApp messages)
The plugin runs as an MCP server that connects to WhatsApp via Baileys, receives incoming messages, and pushes them to Claude Code as channel notifications. Claude can reply using the reply tool.
Features (v0.0.3)
- Production-grade stability — connection patterns based on OpenClaw's proven WhatsApp gateway
- 515 is normal — WhatsApp restart requests are handled gracefully (reconnect in 2s, not crash)
- Never crashes the process — only stops on 440 (conflict) or 401 (logout); everything else reconnects
- Exponential backoff with jitter — factor 1.8, jitter 25%, max 30s, reset after healthy period
- Watchdog — detects stale connections (30min timeout) and forces reconnect
- Credential backup — auto-backup before each save, auto-restore if corrupted
- Permission relay — approve Claude Code tool use from your phone ("yes xxxxx" / "no xxxxx")
- getMessage handler — required for E2EE retry in Baileys v7
- Crypto error recovery — Baileys crypto errors trigger reconnect instead of crash
- Graceful shutdown — clean exit on SIGTERM/SIGINT/stdin close
Requirements
- Node.js 20+ (Bun is NOT supported — lacks WebSocket events Baileys needs)
- Claude Code 2.1.80+ (with Channels support)
- WhatsApp account (regular or Business)
Quick Start
1. Clone and install
git clone https://github.com/diogo85/claude-code-whatsapp.git
cd claude-code-whatsapp
npm install
2. Configure MCP server
Add to your project's .mcp.json:
{
"mcpServers": {
"whatsapp": {
"command": "node",
"args": ["/path/to/claude-code-whatsapp/server.cjs"],
"env": {
"WHATSAPP_STATE_DIR": "~/.claude/channels/whatsapp"
}
}
}
}
3. Pair with WhatsApp
mkdir -p ~/.claude/channels/whatsapp/auth
WHATSAPP_STATE_DIR=~/.claude/channels/whatsapp node pair.cjs
The script shows both a QR code and a pairing code. On your phone:
- QR: WhatsApp > Linked Devices > Link a Device — scan the QR
- Code: WhatsApp > Linked Devices > Link a Device > Link with phone number — enter the code
Wait for "✅ WhatsApp connected!" before closing.
4. Start Claude Code
WHATSAPP_STATE_DIR=~/.claude/channels/whatsapp \
claude --dangerously-load-development-channels "server:whatsapp"
On the first run, select "I am using this for local development" when prompted.
5. Access control (optional)
Create ~/.claude/channels/whatsapp/access.json:
{
"allowFrom": ["5511999999999"],
"allowGroups": false,
"allowedGroups": [],
"requireAllowFromInGroups": false
}
allowFrom: [] (empty) = accept messages from anyoneallowFrom: ["5511999999999"] = only from this numberallowGroups: true + allowedGroups: ["xxx@g.us"] = specific groups
Tools
| Tool | Description |
|---|
reply | Send text + file attachments (images, audio, video, documents) |
react | Add an emoji reaction to a message |
download_attachment | Download media from a received message |
fetch_messages | List recent messages from session cache |
Permission Relay
When Claude Code needs permission to run a tool, it can send the request to your WhatsApp:
🔐 Permission request [tbxkq]
Bash: rm -rf /tmp/foo
Reply "yes tbxkq" or "no tbxkq"
Reply from your phone and Claude Code will proceed (or stop). The plugin reacts with ✅ or ❌ to confirm.
Requires Claude Code v2.1.81+ and the claude/channel/permission capability (enabled by default in v0.0.3).
Stability Design
This plugin was rewritten based on analysis of OpenClaw's WhatsApp extension, which runs 24/7 without issues. Key patterns:
