whatsapp-claude-plugin AGENTS.md

AGENTS.md

Guidance for AI coding agents working in this repository. Read this file fully, then use the routing table at the bottom before starting any non-trivial task.

Project Overview

WhatsApp MCP Server plugin for Claude Code — connects WhatsApp as a messaging channel via the linked-device protocol (Baileys). Bidirectional messaging, media, voice transcription, access control, per-group AI personalities, cron tasks. Published on claude.com/plugins.

Tech Stack & Commands

• Runtime: Bun — TypeScript runs directly. No build step. No test suite.
• Deps (only 2 — no new dependencies without the user's explicit approval): @modelcontextprotocol/sdk, @whiskeysockets/[email protected] (4 known rc.9 bugs are patched by patch-baileys.mjs via postinstall).
• Linting: Trunk (prettier, markdownlint, shellcheck, shfmt, checkov, trufflehog).

bun install     # install deps (postinstall runs patch-baileys.mjs)
bun server.ts   # run the MCP server
trunk check     # lint
trunk fmt       # format

Architecture

WhatsApp (phone) ←─ Baileys ─→ MCP Server (server.ts) ←─ stdio ─→ Claude Code
                                      ↓
                       ~/.whatsapp-channel/ (runtime state, never in repo)
                            ├─ access.json
                            ├─ .baileys_auth/
                            ├─ groups/<groupJid>/   (config.md = personality + cron,
                            │                        memory.md = conversation memory)
                            ├─ tasks.md   (agent-maintained open-task list, read by catch_up)
                            └─ inbox/

• server.ts — the entire MCP server in one file (~1900 lines; re-check with wc -l rather than trusting this number). MCP tools exposed to Claude: reply, react, download_attachment, edit_message, status, unreplied, catch_up, list_groups. Also contains: access-control engine (DM policies pairing/allowlist/disabled, group policies, pairing codes with 1-hour TTL, LID↔phone mapping), message pipeline (access gate → routing → mention detection → text/media extraction → optional transcription → 4096-char chunking in length or newline mode per access.json's chunkMode), per-group personality loading, cron parser (reads the ## Cron Jobs section — exactly that heading — in each group's config.md).
• skills/ — user-facing commands: /whatsapp-channel:setup, :configure, :access.
• hooks/hooks.json → hooks-handlers/session-start.sh — onboarding detection at session start.
• scripts/watchdog.sh, scripts/whisper-transcribe.sh — reference scripts users copy out of the repo (watchdog to ~/.whatsapp-channel/watchdog.sh; the whisper script to ~/whisper-transcribe.sh — server.ts hardcodes that home-dir path). Editing them in the repo does NOT affect running deployments until re-copied.