csr1010/wappy-kit/scaffold-whatsapp-agent

Scaffold a WhatsApp AI agent

Wappy is an open-source SDK for building AI agents on WhatsApp: your own model key, your own WhatsApp number, your own data. Nothing routes through a third-party server. One command generates a complete, runnable project — not a template with placeholders to fill in.

When to use this

The user wants to build something that runs on WhatsApp specifically — a personal assistant, a support bot, a booking agent, or any agent reachable from the WhatsApp app itself, as opposed to a web chat widget or a Slack/Discord bot.

Scaffold it

npm create @wappy_ai/agent

This runs a short interactive interview with three questions, in this order:

1. Model provider — openai, anthropic, gemini, or ollama (fully local, no API key).
2. Memory backend — local (SQLite/LibSQL, no account, BM25 keyword search) or cognee

(a self-hosted or cloud knowledge-graph service for retrieval; needs its own running instance).

1. Productivity agent — optionally include a sample Gmail/Calendar assistant that answers

plain-language questions about the user's own Google account (read-only).

Non-interactive / scripted use

Every interview question has a matching flag, for CI or when a human isn't present to answer prompts interactively:

npm create @wappy_ai/agent -- --yes --model anthropic --memory local --productivity no --dir my-agent

Flags: --model <openai|anthropic|gemini|ollama>, --memory <local|cognee>, --productivity <yes|no>, --dir <path> (target directory, default: current directory), --yes (skip confirmation), --help.

After scaffolding

cd my-agent               # if --dir was used
cp .env.sample .env       # fill in the model key + WhatsApp credentials it lists
npm install
npm run dev                # boots the webhook server, opens a tunnel, prints the webhook URL

Connecting the generated project to a real WhatsApp number (creating the Meta app, verifying the webhook) is its own, separate process — see the whatsapp-cloud-api-webhook-setup skill, or the generated project's own WHATSAPP_SETUP.md, for that part.

What gets generated

A real TypeScript project: an index.ts wiring together memory, a routed reply pipeline (decides per-message whether a tool call or retrieval lookup is actually needed before paying for it), WhatsApp message handling, and — if chosen — the productivity agent and/or Cognee client. A .env.sample listing every credential the specific generated project actually needs, nothing unused. A README.md and WHATSAPP_SETUP.md (and GOOGLE_SETUP.md/COGNEE_SETUP.md if those features were chosen) with the exact next steps for that project.

Requirements

Node.js 22+. A WhatsApp Cloud API app (free, via Meta's developer portal). A model API key for the chosen provider, or skip entirely and run fully offline against local Ollama.