whatsapp-cli

whatsapp-cli

Claude Code plugin for full control over WhatsApp on macOS. Read chats, send messages to individuals and groups, search conversations, auto-reply with AI, monitor in real-time, and export chat history.

Features

• Read chats — list conversations, unread messages, starred messages
• Send messages — to contacts and groups (auto-detects group JIDs)
• Search — full-text search across all conversations
• Groups — list groups, members, group info
• Contacts — list, search, resolve names to JIDs
• Auto-reply — AI-powered auto-reply using Claude as response generator
• Monitor — watch chats in real-time for new messages
• Export — export chat history to TXT, JSON, or CSV; export media files
• Interactive REPL — full-featured REPL with history and styled prompts

Requirements

• macOS (uses WhatsApp's local SQLite database)
• WhatsApp desktop app installed and logged in
• Python 3.10+
• Accessibility permissions for sending (System Settings > Privacy & Security > Accessibility)
• Claude Code CLI (for plugin usage and auto-reply)

Installation

Via Claude Code

claude plugins marketplace add marcelrgberger/whatsapp-cli
claude plugins install whatsapp-cli

The CLI backend installs automatically on first /whatsapp use.

Manual

git clone https://github.com/marcelrgberger/whatsapp-cli.git
cd whatsapp-cli/agent-harness
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Usage

Slash Commands

/whatsapp                        List recent chats
/whatsapp unread                 Show unread chats
/whatsapp read "John"            Read messages from John
/whatsapp send "John" Hello!     Send message to John
/whatsapp search "meeting"       Search all messages
/whatsapp groups                 List all groups
/whatsapp export "John" ./out    Export chat history
/whatsapp monitor "John"         Watch for new messages
/whatsapp auto-reply "John"      AI auto-reply

Natural Language

After installing the plugin, just tell Claude what you want:

• "Show my unread WhatsApp messages"
• "What did John say on WhatsApp?"
• "Send a WhatsApp to the SoundClouds group saying I'll be late"
• "Search WhatsApp for the restaurant address"
• "Auto-reply to Max while I'm away"

Direct CLI

whatsapp-cli chat list --limit 10
whatsapp-cli chat unread
whatsapp-cli message get "John" --limit 50
whatsapp-cli message send "John" "Hello!"
whatsapp-cli message search "meeting"
whatsapp-cli group list
whatsapp-cli group info "Family"
whatsapp-cli export chat "John" ./chat.txt --format txt
whatsapp-cli monitor auto-reply --chat "John" --prompt "Reply friendly" --interval 10
whatsapp-cli  # Launches interactive REPL

Command Reference

Chat

Command	Description
chat list [--limit N] [--groups/--no-groups]	List recent chats
chat search <query>	Search chats by name
chat unread	Show unread chats
chat get <name_or_jid>	Get chat details
chat find <phone>	Find chat by phone number

Message

Command	Description
message get <name> [--limit N] [--before/--after DATE]	Get messages
message search <query> [--chat NAME]	Search messages
message starred [--chat NAME]	Get starred messages
message media <name> [--limit N]	Get media messages
message send <name_or_phone> <text>	Send message (contacts & groups)
message count [--chat NAME]	Count messages

Contact

Command	Description
contact list	List contacts
contact search <query>	Search contacts
contact info <name_or_jid>	Contact details
contact resolve <name>	Resolve name to JID

Group

Command	Description
group list	List all groups
group info <name_or_jid>	Group details
group members <name_or_jid>	List group members
group search <query>	Search groups

Monitor

Command	Description
monitor watch [--chat NAME] [--interval N]	Watch for new messages
monitor since <timestamp> [--chat NAME]	Messages since timestamp
monitor auto-reply --chat NAME --prompt PROMPT [--interval N]	AI auto-reply

Export

Command	Description
export chat <name> <output> [--format txt/json/csv]	Export chat history
export media <name> <output_dir>	Export media files

Session

Command	Description
session status	WhatsApp status, DB stats

Auto-Reply with AI

The killer feature — set up Claude as an auto-responder:

whatsapp-cli monitor auto-reply \
  --chat "John" \
  --prompt "You are me, reply casually and friendly. Max 1-2 sentences." \
  --interval 10 \
  --context-messages 20