Claude Whatsapp

💬 WhatsApp for Claude Code

Your WhatsApp number, powered by Claude Code.

Quick Setup · Features · Access · Docs · Going further · Issues

---

With Anthropic's recent policy changes, many users lost access to their AI agents through messaging platforms. While official channel plugins exist for Telegram and Instagram, WhatsApp — the world's most used messaging app — had no solution.

This plugin fills that gap. It connects your WhatsApp number directly to Claude Code, turning it into a fully functional AI agent that responds through WhatsApp.

[Highlights](#highlights)

• [Native WhatsApp channel](#quick-setup) — scan a QR (or use a pairing code on headless servers), pair your contacts, start chatting with Claude.
• [Access control](#access-control) — pairing codes, allowlist, group gating with requireMention, plus per-chat history scope (each chat sees its own history by default; designated owners read all). Nobody talks to your agent without permission, and no chat reads another's history.
• [Permission relay](#permission-requests-over-whatsapp) — when Claude wants to run a tool, get the prompt on WhatsApp; approve or deny with a 👍 reaction or yes reply.
• [Local search, export, and discovery](#search-history-and-export) — every message indexed locally; full-text search, contact and chat discovery, message-context lookup, request older messages from WhatsApp, dump chats to markdown / jsonl / csv.
• [Voice transcription](#voice-transcription-optional) — local Whisper by default (no API keys, 99+ languages); optional cloud providers (Groq / OpenAI) for higher quality on slower hardware.
• [Media pipeline](#media) — inbound images, audio, video, and documents auto-downloaded for Claude to read.
• [Reply shaping](#reply-shaping) — paragraph-aware chunking, optional ack reaction, auto-document for long replies, message editing without push notifications.
• [Inbound debouncing](#inbound-debouncing) — rapid-fire texts from the same sender are batched into a single agent turn, so Claude stops answering mid-thought when the user is still typing.
• [Autonomous mode + web browsing](#autonomous-mode--web-browsing) — combine with --chrome for a fully agentic WhatsApp assistant.
• [Always-on](#always-on-run-as-a-background-service) — launchd, systemd, or Task Scheduler recipes included.
• [Multiple agents](#multiple-agents) — run separate numbers from separate folders, each isolated.

[Prerequisites](#prerequisites)

• Node.js v18+

[Quick Setup](#quick-setup)

1. Create a folder for your WhatsApp agent.

Each agent lives in its own folder. Create one and open Claude Code there:

mkdir ~/my-whatsapp-agent && cd ~/my-whatsapp-agent
claude

2. Install the plugin.

Inside Claude Code, add the marketplace:

/plugin marketplace add crisandrews/claude-whatsapp

Then install the plugin:

/plugin install whatsapp@claude-whatsapp

When prompted for scope, select "Install for you, in this repo only (local scope)" — this keeps the agent isolated to this folder.

3. Close and relaunch with the WhatsApp channel.

Exit Claude Code (/exit or Ctrl+C), then relaunch:

claude --dangerously-load-development-channels plugin:whatsapp@claude-whatsapp --dangerously-skip-permissions

> --dangerously-skip-permissions lets the agent run without asking for confirmation on every action — recommended for a smooth experience. First launch installs dependencies in the background (~60-90s). Subsequent launches are instant.

4. Link your number.

/whatsapp:configure

Opens a QR code on your screen. Scan it with WhatsApp > Settings > Linked Devices > Link a Device.

> Headless server / no camera? Run /whatsapp:configure pair +5491155556666 first. The next link cycle generates an 8-character code instead of a QR — read it from the terminal, then on your phone open WhatsApp > Linked Devices > Link with phone number and type it in.

Session is saved — you won't need to link again unless you log out.

5. Pair.

Message your WhatsApp number from another phone. It replies with a 6-character code. In Claude Code:

/whatsapp:access pair 

6. Lock it down.

/whatsapp:access policy allowlist

Now only your approved contacts can reach Claude.

[Documentation](#documentation)

In-depth guides, each with worked examples end-to-end. The README is the at-a-glance reference; these pages are where the tutorials live.

Setup & access

• [docs/access.md](docs/access.md) — DM access tutorial: pairing flow, the three policies, JID formats, recovery.
• [docs/groups.md](docs/groups.md) — adding the bot to a WhatsApp group, the four access policies, discovery flow, member discovery, edge cases.

Runtime reference

• [docs/configuration.md](docs/configuration.md) — every /whatsapp:configure sub-command (linking, audio, reply shaping, inbound debouncing, auth migration, reset) and every key in config.json.
• [docs/tools.md](docs/tools.md) — per-tool reference (reply, react, search_messages, fetch_history, …) with natural-language examples and pitfalls.
• [docs/permission-relay.md](docs/permission-relay.md) — how Claude Code's permission prompts reach your phone, how to respond from text or reaction.
• [docs/media-voice.md](docs/media-voice.md) — inbound media runtime: layout, the 50 MB cap, the inbox/ sandbox, voice transcription end-to-end, stickers / locations / contacts.
• [docs/search-export.md](docs/search-export.md) — full-text search, FTS5 query matrix, fetch_history flow, export formats.

Operations & integration

• [docs/operations.md](docs/operations.md) — background service (launchd/systemd/Task Scheduler), updates, cache, multi-instance, logs, reconnection.
• [docs/state-contract.md](docs/state-contract.md) — public contract for companion plugins: channel dir, public files, MCP capabilities, ClawCode integration walkthrough.
• [docs/scope-envelope-contract.md](docs/scope-envelope-contract.md) — cross-plugin per-inbound request envelope contract. Mirrored byte-exact with peer plugins that consume it. Wire-level constants, payload schema, validation rules, threat model.
• [docs/troubleshooting.md](docs/troubleshooting.md) — symptoms → causes → fixes; covers every connection state and the most common gotchas.

[Access control](#access-control)

[DMs](#access-dms)

> Deep dive with worked examples: [docs/access.md](docs/access.md).

| Command | Description | | --- | --- | | /whatsapp:access | List allowed users, pending pairings, and current policy | | /whatsapp:access pair | Approve a pending pairing | | /whatsapp:access deny | Reject a pending pairing | | /whatsapp:access allow | Add a user directly | | /whatsapp:access revoke | Remove a user | | /whatsapp:access policy | Set DM policy: pairing, allowlist, or disabled | | /whatsapp:access show-owner / set-owner | Show or designate the cross-chat owner JID | | /whatsapp:access show-scope / set-scope | Show or configure per-chat history scope |

Default policy is pairing. IDs are WhatsApp JIDs — format depends on your Baileys version (e.g. 56912345678@s.whatsapp.net or 12345678901234@lid). Check /whatsapp:access to see the exact IDs.

Per-chat history scope. Nine read/exfil tools (search_messages, fetch_history, export_chat, list_group_senders, get_message_context, get_chat_analytics, list_chats, search_contact, forward_message) are gated by chat. Owners (ownerJids) read every indexed chat; non-owner chats are sandboxed to their own history by default. Override per-chat with set-scope. First pair after a fresh install seeds ownerJids automatically. Terminal operator can set WHATSAPP_OWNER_BYPASS=1 in the environment for full access without an inbound. Full model: [docs/access.md#history-scope](docs/access.md#history-scope).

[Groups](#access-groups)

> Deep dive with worked examples: [docs/groups.md](docs/groups.md).

Group access is fully independent of DM access. Allowing someone in a group does NOT let them DM the bot, and pairing a DM contact does NOT auto-allow them in any group.

| Command | Description | | --- | --- | | /whatsapp:access add-group | Allow a group, mention-only (default). | | /whatsapp:access add-group --no-mention | Allow a group, open delivery (every message goes to Claude). | | /whatsapp:access group-allow | Restrict the group to specific members. | | /whatsapp:access group-revoke | Remove a member from the group's whitelist. | | /whatsapp:access remove-group | Stop accepting messages from the group entirely. |

[Features](#features)

[Tools](#tools)

> Per-tool reference with arguments, returns, examples, and pitfalls: [docs/tools.md](docs/tools.md).

The plugin exposes 52 MCP tools across 12 categories. Each entry below is a single tool — see the docs for arguments and worked examples.

Messaging — reply, react, edit_message, delete_message, mark_read, send_poll

Message types — send_location, send_contact, send_link_preview, send_voice_note, forward_message, pin_message

Discovery & search — list_chats, search_messages, search_contact, get_message_context, fetch_history, list_group_senders

Chat management — archive_chat, pin_chat, mute_chat, delete_chat, clear_chat

Group admin (existing groups) — get_group_metadata, update_group_subject, update_group_description, update_group_settings, add_participants, remove_participants, promote_admins, demote_admins, leave_group, toggle_group_ephemeral, handle_join_request

Group lifecycle — create_group, join_group, get_invite_code, revoke_invite_code

Contacts — check_number_exists, get_business_profile, block_contact, unblock_contact

Profile self-mgmt — update_profile_name, update_profile_status, update_profile_picture, remove_profile_picture, update_privacy

Calls — reject_call

Presence — send_presence

Analytics & export — get_chat_analytics, export_chat

Media — download_attachment

What's NOT a plugin feature (yet)

• Standalone install path (Smithery / non-Claude-Code MCP clients) — the plugin currently runs only inside Claude Code's plugin lifecycle.
• WhatsApp Business catalog management, newsletters, status / story posts, view-once messages — niche features intentionally out of scope.

[Reactions](#reactions)

Reactions behave differently depending on what the user reacts to:

On a permission request (a 🔐 Claude wants to run … message): the plugin intercepts the reaction directly and converts it into an approve/deny decision sent back to Claude Code. The terminal prompt clears automatically.

| Reaction | Meaning | | --- | --- | | 👍 / ✅ | Approve the pending tool | | 👎 / ❌ | Deny the pending tool |

Skin-tone variants of 👍 / 👎 also work. Pending requests time out after 5 minutes; the terminal-side dialog stays active either way, so you can also approve there.

On a regular message: the reaction is forwarded to Claude as [Reacted with X] and Claude interprets it from context — typically 👍 as "ok/proceed" and 👎 as "no/stop".

[Permission requests over WhatsApp](#permission-requests-over-whatsapp)

> Deep dive with worked examples: [docs/permission-relay.md](docs/permission-relay.md).

When Claude Code asks to run a tool (e.g. a Bash command), the plugin broadcasts the request to every allowlisted DM contact:

🔐 Claude wants to run *Bash*
ls -la /tmp

Reply *yes abcde* / *no abcde* or react 👍 / 👎.

Respond with text (yes / no , case-insensitive) or a reaction (👍 / ✅ to allow, 👎 / ❌ to deny). Whoever responds first wins; the terminal prompt remains active as a fallback. Pending requests expire after 5 minutes.

[Search, history, and export](#search-history-and-export)

> Deep dive with worked examples: [docs/search-export.md](docs/search-export.md).

Every inbound and outbound message — including reactions, edits, file captions, and history backfills — is indexed locally to SQLite + FTS5. Claude can full-text search your chats, pull older messages from WhatsApp on demand, and export a chat as markdown / jsonl / csv. The store is local-only, user-only permissions (0600), and safe to delete to wipe history.

[Reply shaping](#reply-shaping)

> Deep dive with worked examples: [docs/configuration.md#reply-shaping](docs/configuration.md#reply-shaping).

Several knobs control how Claude's outbound messages look on WhatsApp. All set via /whatsapp:configure:

| Command | Effect | | --- | --- | | chunk-mode newline | Split long replies at the nearest paragraph / line / space instead of cutting at 4096 chars | | reply-to first (default) / all / off | Which chunks of a long reply quote the user's original message | | ack 👀 | React with this emoji as soon as a message arrives, before Claude composes a reply | | ack off | Disable the ack reaction | | document threshold 4000 | Send replies above N chars as a single .md / .txt attachment instead of many chunked messages | | document threshold off | Always chunk, never auto-document | | document format md / txt / auto | Force the auto-document filename / MIME (default auto picks based on content) |

[Inbound debouncing](#inbound-debouncing)

> Deep dive with worked examples: [docs/configuration.md#inbound-debouncing](docs/configuration.md#inbound-debouncing).

When a user fires several plain-text messages in quick succession ("hi" → "actually" → "can you…"), the plugin holds them in a 2-second sliding window per (chat, sender) and hands the whole batch to Claude as one agent turn — so Claude doesn't start answering the first message while the user is still composing. Attachments, voice notes, reactions, and permission replies bypass the buffer and flush any pending text first so ordering is preserved.

Tune via inboundDebounceMs in config.json (default 2000; set to 0 to disable and get the pre-1.12 one-message-one-turn behavior).

[Media](#media)

> Deep dive with worked examples: [docs/media-voice.md](docs/media-voice.md).

Inbound photos, voice messages, videos, and documents are automatically downloaded to /inbox/ — /.whatsapp/inbox/ for local-scope installs, ~/.claude/channels/whatsapp/inbox/ for the global fallback. Max 50 MB per inbound file. The file path is included in the notification so Claude can read or reference it.

Stickers, locations, and contacts are forwarded as descriptive text ([Sticker received], [Location: lat, lng], [Contact: name]) without downloading a file.

[Voice transcription (optional)](#voice-transcription-optional)

> Deep dive with worked examples: [docs/media-voice.md#voice-transcription-end-to-end](docs/media-voice.md#voice-transcription-end-to-end) and [docs/configuration.md#voice-transcription](docs/configuration.md#voice-transcription).

By default, voice messages arrive as [Voice message received] with the audio file saved. To enable automatic local transcription:

/whatsapp:configure audio

The Whisper model (~77MB for base) downloads on the first voice message and is cached permanently. Runs entirely on your machine — 99+ languages supported, no API keys needed. Recommended: set your primary language explicitly (/whatsapp:configure audio es) for short-message accuracy.

Model size (tiny / base / small) and quality (fast / balanced / best) are configurable — full tradeoff tables in [docs/configuration.md#voice-transcription](docs/configuration.md#voice-transcription).

Disable with /whatsapp:configure audio off.

**Cloud provider

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: crisandrews
• Source: crisandrews/claude-whatsapp
• License: MIT
• Homepage: https://github.com/crisandrews/claude-whatsapp#quick-setup

Install and usage instructions live in the source repository linked above.