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.

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

Dashboard

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

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

MCP

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.

License

MIT © W Agent contributors