W Agent

W Agent: your WhatsApp, with a brain.
A self-hosted bridge that gives an AI agent continuous, searchable context over your WhatsApp chats — and lets it reply for you, safely.

W Agent keeps your archive in your Postgres, stages every outbound draft for approval (unless you opt a chat into auto-send), and exposes the same context to Claude Desktop and other MCP clients. The WhatsApp transport is swappable: unofficial Baileys for personal companion use, or the official Meta Cloud API for business messaging.

Operational warning. The default bridge uses Baileys (unofficial multi-device protocol) and carries real account ban / restriction risk. Prefer a dedicated number. For business workloads, set WHATSAPP_PROVIDER=meta. See docs/security.md and docs/providers.md.

<!-- Optional: drop a ~60s screen capture at docs/assets/demo.gif -->

Features

• Provider-adapter WhatsApp bridge — Baileys (personal / multi-device) or Meta Cloud API
• Durable ingest — inbound messages → BullMQ → Postgres (contacts, chats, messages, media)
• History sync & backfill — Baileys history chunks and on-demand per-chat backfill
• Hybrid search — OpenAI embeddings + pgvector merged with Postgres full-text search
• Rolling chat summaries — cheap-model memory on a message cadence
• Engagement engine — allowlists, group @-mentions, opt-in/out, owner /agent commands
• Safety stack — injection heuristics (+ optional LLM classifier), outbound chat lock, secret redaction
• Approval outbox — drafts notify the owner; approve in the dashboard (or per-chat auto-send)
• Send hygiene — quotas, quiet hours, typing delays, exponential WA rate-limit cooldown
• MCP server — stdio + HTTP/SSE tools, resources, and prompts
• Ops — watchdog, /healthz, atomic auth persistence, chaos + red-team scripts

Architecture

flowchart TB
  subgraph clients [Clients]
    WA[WhatsApp]
    Dash[Dashboard]
    MCPC[MCP clients<br/>Claude / ChatGPT / custom]
  end

  subgraph bridge [Bridge]
    Prov["WhatsAppProvider<br/>baileys | meta"]
  end

  subgraph queues [Queues - Redis / BullMQ]
    IngestQ[ingest]
    EmbedQ[embed]
    SumQ[summary]
    Outbox[outbox sender]
  end

  subgraph storage [Storage]
    PG[(Postgres + pgvector)]
    Auth[(Auth / media volumes)]
  end

  subgraph agent [Agent + safety]
    Engage[Engagement]
    Guard[Injection guard]
    Loop[Agent loop + tools]
    Draft[Draft + owner notify]
  end

  subgraph mcp [MCP]
    Stdio[stdio]
    HTTPMCP[HTTP + SSE]
  end

  WA <--> Prov
  Prov -->|ProviderMessage| IngestQ
  IngestQ --> PG
  IngestQ --> EmbedQ
  EmbedQ --> PG
  IngestQ --> SumQ
  SumQ --> PG
  Prov --> Auth

  PG --> Engage
  Engage --> Guard
  Guard --> Loop
  Loop --> Draft
  Draft --> PG
  Dash --> PG
  Dash -->|approve| Outbox
  Outbox --> Prov

  MCPC --> Stdio
  MCPC --> HTTPMCP
  Stdio --> PG
  HTTPMCP --> PG
  Stdio --> Draft
  HTTPMCP --> Draft

Layer detail: docs/architecture.md. Provider trade-offs: docs/providers.md.

Quickstart

Requires Docker, Node.js 22+, and pnpm 9+.

git clone https://github.com/Chessing234/w-agent.git
cd w-agent

cp .env.example .env
# Required: OPENAI_API_KEY
# Recommended: DASHBOARD_TOKEN (long random secret)

docker compose up -d --build
pnpm install && pnpm migrate

# Pair: QR in app logs or the dashboard
docker compose logs -f app
# — or —
# DASHBOARD_TOKEN=… pnpm dashboard:dev  → http://localhost:3200/pairing

Open WhatsApp → Linked devices → scan the QR. When the session shows connected, you are done for the default Baileys path.

curl -sS "http://127.0.0.1:3099/healthz"

Local Postgres/Redis only (host-run agent): make up-dev — see examples/docker-compose.override.yml.

Documentation

Document	Contents
docs/architecture.md	Bridge, queue, storage, agent, MCP; provider-adapter rationale
docs/security.md	Injection threat model, approval pipeline, ban risk, data locality
SECURITY.md	Responsible disclosure
docs/mcp-clients.md	Claude Desktop & ChatGPT MCP snippets
docs/providers.md	Baileys vs Meta Cloud API
examples/demo.md	Demo flows, red-team, backup/restore
CHANGELOG.md	Release notes
CONTRIBUTING.md	Dev setup, tests, PR expectations

Dashboard

pnpm dashboard:dev   # http://localhost:3200 — token: DASHBOARD_TOKEN

Routes: /pairing, /chats, /approvals, /health.

MCP

Transport	Command	Auth
stdio	pnpm mcp	Local process (Claude Desktop)
HTTP + SSE	App when MCP_AUTH_TOKEN is set, or pnpm mcp:http	Bearer / X-MCP-Token / ?token=

Full client setup: docs/mcp-clients.md.

Development

pnpm install && cp .env.example .env
make up-dev && pnpm migrate
pnpm dev
pnpm dashboard:dev

pnpm lint && pnpm typecheck
pnpm test                 # Docker required (testcontainers Postgres)
pnpm test:coverage        # ≥80% on src/safety + src/agent
pnpm redteam              # 10 canned injection payloads
pnpm backup               # Postgres + auth → backups/*.tar.gz

CI (.github/workflows/ci.yml): lint, typecheck, coverage on Node 22 with Redis; Postgres via testcontainers.

Configuration

Validated in src/config.ts (Zod). Full list: .env.example.

Variable	Purpose
OPENAI_API_KEY	Embeddings, summaries, agent, optional classifiers
DATABASE_URL / REDIS_URL	Postgres + Redis
WHATSAPP_PROVIDER	baileys (default) | meta | evolution (reserved)
WHATSAPP_AUTH_DIR / MEDIA_DIR	Baileys auth + inbound media
DASHBOARD_TOKEN / MCP_AUTH_TOKEN	Dashboard / remote MCP secrets
HEALTHZ_PORT	Aggregated /healthz
OWNER_TIMEZONE / QUIET_HOURS_* / SEND_*	Auto-send safety

License

MIT © W Agent contributors