add-whatsapp
Skill98 starsChanged 8 months agoApache-2.0View on GitHub
Add WhatsApp as a channel. Can replace other channels entirely or run alongside them. Uses QR code or pairing code for authentication.
- Reads credentials
- Deletes or force-pushes
- Installs packages
9 other projects use a version of this, 4 of them edited.
Adopted by
Most recently taken up by
- nanocoai/nanoclawtheir own version, first seen Nov 15, 2026
- ss2code/nanoclaw-opsedited, first seen Oct 15, 2026
- prathish-ks/isthmustheir own version, first seen Oct 12, 2026
- gavrielc/nanoclawtheir own version, first seen Oct 8, 2026
- qwibitai/nanoclawtheir own version, first seen Oct 8, 2026
- TomGranot/groupguardtheir own version, first seen Sep 3, 2026
Used with
Projects with it also use add-anydoc, add-clidash and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
TomGranotSkilladd-anydoc
Add local office-document-to-Markdown conversion to NanoClaw agent containers with the pinned Firecrawl AnyDoc CLI. Use when agents need to read attached Word, PowerPoint, Excel, OpenDocument, RTF, EPUB, CSV, or text-based PDF files without uploading them to a hosted parser.
Also in 5 projects that use this
TomGranotSkilladd-clidash
Add clidash — a zero-dependency, read-only web dashboard that derives its tabs and tables at runtime from any CLI that lists resources as JSON. Ships pre-wired for NanoClaw's ncl CLI (agent groups, sessions, channels, users, roles), plus message-activity charts, a log tail, and a read-only file viewer for group skills/CLAUDE.md/profiles.
Also in 5 projects that use this
qwibitaiSkilladd-iron-proxy
Install or refresh Iron Proxy and its official Iron Control web console for NanoClaw. Use when selecting the Iron gateway, adding its management UI, configuring credentials and grants, or restoring the proxy, approval bridge, and agent guidance.
Also in 4 projects that use this
qwibitaiSkilladd-mattermost
Add a self-hosted or cloud Mattermost bot channel through the Chat SDK bridge, reusing a healthy server when available and linking to official server setup guidance when needed.
Also in 4 projects that use this
b1rdmaniaSkillmigrate-memory
Migrate from monolith CLAUDE.md to the three-file memory system (identity + state + log). Non-destructive — backs up the original first.
Also in 6 projects that use this
nanocoaiSkilladd-cursor
Use Cursor (local Agent SDK) as a full agent provider — planning, tool orchestration, MCP tools, session resume — alongside or instead of Claude. Cursor-account sign-in or API key, held by the credential gateway. Per-group via `ncl groups config update --provider cursor`. Distinct from using Cursor as a cloud agent (those run on Cursor VMs and are not this provider).
Also in 3 projects that use this
- +5 more from TomGranot
- +1 more from qwibitai
Other versions9 projects use a version of this.
Word for word · 0
None found.
Edited · 4
- microsoft/amplifier-app-nanoclaw★ 520% same
- breakcafe/picoclaw★ 183% same
- mcarmona1064-cell/clawbridge-codex★ 127% same
- ss2code/nanoclaw-ops★ 119% same
Wrote their own version · 5
- gavrielc/nanoclaw★ 31ksame name
- nanocoai/nanoclaw★ 31ksame name
- qwibitai/nanoclaw★ 31ksame name
- TomGranot/groupguard★ 3same name
- prathish-ks/isthmus★ 2same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository20 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- add-dingtalkSkill
- add-discordSkill
- add-gmailSkill
- add-ollama-toolSkill
- add-parallelSkill
- add-slackSkill
- add-telegramSkill
- add-telegram-swarmSkill
- add-vaspSkill
- add-voice-transcriptionSkill
- convert-to-apple-containerSkill
- customizeSkill
- debugSkill
- get-qodo-rulesSkill
- qodo-pr-resolverSkill
- setupSkill
- update-matclawSkill
- use-local-whisperSkill
- x-integrationSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
13 rules. 0 are common, 6 are distinctive, and 7 are very specific to this project.
0
Common
Most of the 9 edited versions we read keep these.
6
Distinctive
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 14
Check if WhatsApp is already configured.
- Distinctive: line 22
Check whether the environment is headless (no display server):
- Very specific: line 30
Use AskUserQuestion to collect configuration.
- Very specific: line 32
If IS_HEADLESS=true AND not WSL → AskUserQuestion: How do you want to authenticate WhatsApp?
- Distinctive: line 41
If they chose pairing code:
- Distinctive: line 53
Verify the code was placed correctly:
- Very specific: line 192
DM with bot: Ask for the bot's phone number.
- Distinctive: line 194
Group (solo, existing): Run group sync and list available groups:
- Distinctive: line 288
If pairing code keeps failing, switch to QR-browser auth instead:
- Distinctive: line 313
Run group metadata sync:
- Very specific: line 323
If running npm run dev while the service is active:
- Very specific: line 342
Delete auth credentials: rm -rf store/auth/
- Very specific: line 343
Remove WhatsApp registrations: sqlite3 store/messages.db "DELETE FROM registered_groups WHERE jid LIKE '%@g.us' OR jid LIKE …
“Common” is measured: kept by at least 6 in 10 of the 9 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Add WhatsApp Channel
This skill adds WhatsApp support to MatClaw. It installs the WhatsApp channel code, dependencies, and guides through authentication, registration, and configuration.
Phase 1: Pre-flight
Check current state
Check if WhatsApp is already configured. If store/auth/ exists with credential files, skip to Phase 4 (Registration) or Phase 5 (Verify).
ls store/auth/creds.json 2>/dev/null && echo "WhatsApp auth exists" || echo "No WhatsApp auth"Detect environment
Check whether the environment is headless (no display server):
[[ -z "$DISPLAY" && -z "$WAYLAND_DISPLAY" && "$OSTYPE" != darwin* ]] && echo "IS_HEADLESS=true" || echo "IS_HEADLESS=false"Ask the user
Use AskUserQuestion to collect configuration. Adapt auth options based on environment:
If IS_HEADLESS=true AND not WSL → AskUserQuestion: How do you want to authenticate WhatsApp?
- Pairing code (Recommended) - Enter a numeric code on your phone (no camera needed, requires phone number)
- QR code in terminal - Displays QR code in the terminal (can be too small on some displays)
Otherwise (macOS, desktop Linux, or WSL) → AskUserQuestion: How do you want to authenticate WhatsApp?
- QR code in browser (Recommended) - Opens a browser window with a large, scannable QR code
- Pairing code - Enter a numeric code on your phone (no camera needed, requires phone number)
- QR code in terminal - Displays QR code in the terminal (can be too small on some displays)
If they chose pairing code:
AskUserQuestion: What is your phone number? (Include country code without +, e.g., 1234567890)
Phase 2: Verify Code
Apply the skill to install the WhatsApp channel code and dependencies:
npx tsx scripts/apply-skill.ts .claude/skills/add-whatsappVerify the code was placed correctly:
test -f src/channels/whatsapp.ts && echo "WhatsApp channel code present" || echo "ERROR: WhatsApp channel code missing — re-run skill apply"Verify dependencies
node -e "require('@whiskeysockets/baileys')" 2>/dev/null && echo "Baileys installed" || echo "Installing Baileys..."If not installed:
npm install @whiskeysockets/baileys qrcode qrcode-terminalValidate build
npm run buildBuild must be clean before proceeding.
Phase 3: Authentication
Clean previous auth state (if re-authenticating)
rm -rf store/auth/Run WhatsApp authentication
For QR code in browser (recommended):
npx tsx setup/index.ts --step whatsapp-auth -- --method qr-browser(Bash timeout: 150000ms)
Tell the user:
A browser window will open with a QR code.
- Open WhatsApp > Settings > Linked Devices > Link a Device
- Scan the QR code in the browser
- The page will show "Authenticated!" when done
For QR code in terminal:
npx tsx setup/index.ts --step whatsapp-auth -- --method qr-terminalTell the user to run npm run auth in another terminal, then:
- Open WhatsApp > Settings > Linked Devices > Link a Device
- Scan the QR code displayed in the terminal
For pairing code:
npx tsx setup/index.ts --step whatsapp-auth -- --method pairing-code --phone <their-phone-number>(Bash timeout: 150000ms). Display PAIRING_CODE from output.
Tell the user:
A pairing code will appear. Enter it within 60 seconds — codes expire quickly.
- Open WhatsApp > Settings > Linked Devices > Link a Device
- Tap Link with phone number instead
- Enter the code immediately
If the code expires, re-run the command — a new code will be generated.
If failed: qr_timeout → re-run. logged_out → delete store/auth/ and re-run. 515 → re-run. timeout → ask user, offer retry.
Verify authentication succeeded
test -f store/auth/creds.json && echo "Authentication successful" || echo "Authentication failed"Configure environment
Channels auto-enable when their credentials are present — WhatsApp activates when store/auth/creds.json exists.
Sync to container environment:
mkdir -p data/env && cp .env data/env/envPhase 4: Registration
Configure trigger and channel type
Get the bot's WhatsApp number: node -e "const c=require('./store/auth/creds.json');console.log(c.me.id.split(':')[0].split('@')[0])"
AskUserQuestion: Is this a shared phone number (personal WhatsApp) or a dedicated number (separate device)?
- Shared number - Your personal WhatsApp number (recommended: use self-chat or a solo group)
- Dedicated number - A separate phone/SIM for the assistant
AskUserQuestion: What trigger word should activate the assistant?
- @Andy - Default trigger
- @Claw - Short and easy
- @Claude - Match the AI name
AskUserQuestion: What should the assistant call itself?
- Andy - Default name
- Claw - Short and easy
- Claude - Match the AI name
AskUserQuestion: Where do you want to chat with the assistant?
Shared number options:
- Self-chat (Recommended) - Chat in your own "Message Yourself" conversation
- Solo group - A group with just you and the linked device
- Existing group - An existing WhatsApp group
Dedicated number options:
- DM with bot (Recommended) - Direct message the bot's number
- Solo group - A group with just you and the bot
- Existing group - An existing WhatsApp group
Get the JID
Self-chat: JID = your phone number with @s.whatsapp.net. Extract from auth credentials:
node -e "const c=JSON.parse(require('fs').readFileSync('store/auth/creds.json','utf-8'));console.log(c.me?.id?.split(':')[0]+'@s.whatsapp.net')"DM with bot: Ask for the bot's phone number. JID = NUMBER@s.whatsapp.net
Group (solo, existing): Run group sync and list available groups:
npx tsx setup/index.ts --step groups
npx tsx setup/index.ts --step groups --listThe output shows JID|GroupName pairs. Present candidates as AskUserQuestion (names only, not JIDs).
Register the chat
npx tsx setup/index.ts --step register \
--jid "<jid>" \
--name "<chat-name>" \
--trigger "@<trigger>" \
--folder "whatsapp_main" \
--channel whatsapp \
--assistant-name "<name>" \
--is-main \
--no-trigger-required # Only for main/self-chatFor additional groups (trigger-required):
npx tsx setup/index.ts --step register \
--jid "<group-jid>" \
--name "<group-name>" \
--trigger "@<trigger>" \
--folder "whatsapp_<group-name>" \
--channel whatsappPhase 5: Verify
Build and restart
npm run buildRestart the service:
# macOS (launchd)
launchctl kickstart -k gui/$(id -u)/com.matclaw
# Linux (systemd)
systemctl --user restart matclaw
# Linux (nohup fallback)
bash start-matclaw.shTest the connection
Tell the user:
Send a message to your registered WhatsApp chat:
- For self-chat / main: Any message works
- For groups: Use the trigger word (e.g., "@Andy hello")
The assistant should respond within a few seconds.
Check logs if needed
tail -f logs/matclaw.logTroubleshooting
QR code expired
QR codes expire after ~60 seconds. Re-run the auth command:
rm -rf store/auth/ && npx tsx src/whatsapp-auth.tsPairing code not working
Codes expire in ~60 seconds. To retry:
rm -rf store/auth/ && npx tsx src/whatsapp-auth.ts --pairing-code --phone <phone>Enter the code immediately when it appears. Also ensure:
- Phone number includes country code without
+(e.g.,1234567890) - Phone has internet access
- WhatsApp is updated to the latest version
If pairing code keeps failing, switch to QR-browser auth instead:
rm -rf store/auth/ && npx tsx setup/index.ts --step whatsapp-auth -- --method qr-browser"conflict" disconnection
This happens when two instances connect with the same credentials. Ensure only one MatClaw process is running:
pkill -f "node dist/index.js"
# Then restartBot not responding
Check:
- Auth credentials exist:
ls store/auth/creds.json - Chat is registered:
sqlite3 store/messages.db "SELECT * FROM registered_groups WHERE jid LIKE '%whatsapp%' OR jid LIKE '%@g.us' OR jid LIKE '%@s.whatsapp.net'" - Service is running:
launchctl list | grep matclaw(macOS) orsystemctl --user status matclaw(Linux) - Logs:
tail -50 logs/matclaw.log
Group names not showing
Run group metadata sync:
npx tsx setup/index.ts --step groupsThis fetches all group names from WhatsApp. Runs automatically every 24 hours.
After Setup
If running npm run dev while the service is active:
# macOS:
launchctl unload ~/Library/LaunchAgents/com.matclaw.plist
npm run dev
# When done testing:
launchctl load ~/Library/LaunchAgents/com.matclaw.plist
# Linux:
# systemctl --user stop matclaw
# npm run dev
# systemctl --user start matclawRemoval
To remove WhatsApp integration:
- Delete auth credentials:
rm -rf store/auth/ - Remove WhatsApp registrations:
sqlite3 store/messages.db "DELETE FROM registered_groups WHERE jid LIKE '%@g.us' OR jid LIKE '%@s.whatsapp.net'" - Sync env:
mkdir -p data/env && cp .env data/env/env - Rebuild and restart:
npm run build && launchctl kickstart -k gui/$(id -u)/com.matclaw(macOS) ornpm run build && systemctl --user restart matclaw(Linux)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

