agentleFS
DingyangLyuDingyangLyu/MatClaw/.claude/skills/add-whatsapp/SKILL.md

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

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.
  • TomGranotSkill

    add-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

  • TomGranotSkill

    add-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

  • qwibitaiSkill

    add-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

  • qwibitaiSkill

    add-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

  • b1rdmaniaSkill

    migrate-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

  • nanocoaiSkill

    add-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

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
  1. Very specific:

    Check if WhatsApp is already configured.

    line 14
  2. Distinctive:

    Check whether the environment is headless (no display server):

    line 22
  3. Very specific:

    Use AskUserQuestion to collect configuration.

    line 30
  4. Very specific:

    If IS_HEADLESS=true AND not WSL → AskUserQuestion: How do you want to authenticate WhatsApp?

    line 32
  5. Distinctive:

    If they chose pairing code:

    line 41
  6. Distinctive:

    Verify the code was placed correctly:

    line 53
  7. Very specific:

    DM with bot: Ask for the bot's phone number.

    line 192
  8. Distinctive:

    Group (solo, existing): Run group sync and list available groups:

    line 194
  9. Distinctive:

    If pairing code keeps failing, switch to QR-browser auth instead:

    line 288
  10. Distinctive:

    Run group metadata sync:

    line 313
  11. Very specific:

    If running npm run dev while the service is active:

    line 323
  12. Very specific:

    Delete auth credentials: rm -rf store/auth/

    line 342
  13. Very specific:

    Remove WhatsApp registrations: sqlite3 store/messages.db "DELETE FROM registered_groups WHERE jid LIKE '%@g.us' OR jid LIKE …

    line 343

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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-whatsapp

Verify 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-terminal

Validate build

npm run build

Build 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.

  1. Open WhatsApp > Settings > Linked Devices > Link a Device
  2. Scan the QR code in the browser
  3. The page will show "Authenticated!" when done

For QR code in terminal:

npx tsx setup/index.ts --step whatsapp-auth -- --method qr-terminal

Tell the user to run npm run auth in another terminal, then:

  1. Open WhatsApp > Settings > Linked Devices > Link a Device
  2. 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.

  1. Open WhatsApp > Settings > Linked Devices > Link a Device
  2. Tap Link with phone number instead
  3. 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/env

Phase 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 --list

The 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-chat

For additional groups (trigger-required):

npx tsx setup/index.ts --step register \
  --jid "<group-jid>" \
  --name "<group-name>" \
  --trigger "@<trigger>" \
  --folder "whatsapp_<group-name>" \
  --channel whatsapp

Phase 5: Verify

Build and restart

npm run build

Restart the service:

# macOS (launchd)
launchctl kickstart -k gui/$(id -u)/com.matclaw

# Linux (systemd)
systemctl --user restart matclaw

# Linux (nohup fallback)
bash start-matclaw.sh

Test 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.log

Troubleshooting

QR code expired

QR codes expire after ~60 seconds. Re-run the auth command:

rm -rf store/auth/ && npx tsx src/whatsapp-auth.ts

Pairing 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:

  1. Phone number includes country code without + (e.g., 1234567890)
  2. Phone has internet access
  3. 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 restart

Bot not responding

Check:

  1. Auth credentials exist: ls store/auth/creds.json
  2. 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'"
  3. Service is running: launchctl list | grep matclaw (macOS) or systemctl --user status matclaw (Linux)
  4. Logs: tail -50 logs/matclaw.log

Group names not showing

Run group metadata sync:

npx tsx setup/index.ts --step groups

This 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 matclaw

Removal

To remove WhatsApp integration:

  1. Delete auth credentials: rm -rf store/auth/
  2. Remove WhatsApp registrations: sqlite3 store/messages.db "DELETE FROM registered_groups WHERE jid LIKE '%@g.us' OR jid LIKE '%@s.whatsapp.net'"
  3. Sync env: mkdir -p data/env && cp .env data/env/env
  4. Rebuild and restart: npm run build && launchctl kickstart -k gui/$(id -u)/com.matclaw (macOS) or npm run build && systemctl --user restart matclaw (Linux)

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.