WhatsApp Assistant — local runtime

WhatsApp tools and a graphical UI candidate for Codex, Claude Code and local stdio MCP clients. No local TCP listener or plugin-operated cloud relay. Tool data still enters your chosen AI client/provider's context: Privacy.

Graphical UI candidate

The bundled UI provides connection status, chat search, an unread filter, selected-chat text/media history, bounded older-page loading and a two-step reply confirmation. Attach one user-selected image or file up to 16 MiB, with an optional caption. Raster images show a preview; other files display their name and size. The final confirmation binds the recipient, complete caption and exact file. Files stay in local memory and are never included in model hand-offs. Incoming media up to 16 MiB opens only after an explicit click: raster images, audio and video have a viewer; other files are download-only. Available profile pictures are loaded for visible chats, with initials as fallback. It shares the existing local action layer and keeps view state in memory. Native Codex UI support is UNVERIFIED; the loopback panel can be started explicitly after the frontend has been built:

./scripts/run-ui.sh

Danach die ausgegebene Loopback-URL (standardmaessig http://127.0.0.1:8765/) im Browserpanel oeffnen.

The UI does not start the WhatsApp daemon or link an account automatically. Selected messages can be sent to the model explicitly for summary or drafting in a native host; in a browser panel use the copy action. See UI acceptance, support and terms.

Private Dot UI

The private Secure MCP Tunnel can expose this same MCP App resource and its UI-only actions when its local profile explicitly contains allowUi: true. The default remains false, so existing Dot profiles keep their text-tool behavior and do not gain a UI or media path during an update. The UI session is isolated from other sessions and is checked against the bound WhatsApp account before and after each action. Search and history are still limited to the configured account scope and the existing 30-day boundary.

UI actions return private app metadata rather than model text. A user must explicitly select content before a summary or draft hand-off. Selected files and opened incoming media are limited to 16 MiB and stay in bounded memory; they are not transferred to the model automatically. Text and file sends share the same durable confirmation and duplicate-send protection. Native host rendering and live media delivery remain unverified.

Requirements and risk

macOS, installed Google Chrome, Node.js 22.13+ and pnpm 11.19.0. This is an unofficial OpenWA integration, not affiliated with WhatsApp/Meta. WhatsApp Web changes can break it; unofficial automation may lead to account restrictions. Review the source and make your own informed account-risk decision before setup. Do not use it as a business-critical messaging channel.

OpenWA 4.76.0 is pinned. Its remote runtime patches are disabled. Chrome uses Puppeteer's pipe transport; TLS checking, sandboxing and site isolation are not disabled. Installation skips package lifecycle scripts/browser downloads. Review OpenWA's own package license before using or redistributing dependencies.

Install

From this plugin directory, after explicitly choosing to connect your account:

./scripts/install.sh

Read the QR code yourself in the terminal and scan it with WhatsApp. Never capture/share a QR code, session material, or secrets with an AI agent or issue. The local daemon is installed as a per-user macOS LaunchAgent. The app root is ~/Library/Application Support/WhatsApp Assistant/, outside the plugin/cache. Review and privately back up an existing installation before an update.

Then install the plugin in the chosen Codex/Claude marketplace or print a local MCP configuration from the checkout:

node scripts/mcp-config.mjs claude-desktop
node scripts/mcp-config.mjs cursor
node scripts/mcp-config.mjs vscode
node scripts/mcp-config.mjs generic

The generator prints an absolute-path configuration without modifying settings. Moving the checkout requires regeneration. Do not add secret values to it. Use the shared skill or load the MCP whatsapp-safety prompt. Start a fresh client task after installation. Cached plugin files and running daemons/tasks do not automatically change when source files are edited.

Tools

Interactive agents must show exact recipient/text and wait for a NEW explicit confirmation. The local host cannot cryptographically prove human confirmation or scheduled origin. A model that ignores workflow instructions is a residual risk; do not disable approvals. Unknown delivery must not be retried.

Operations

Run only within an explicitly authorized local operation:

./scripts/status.sh
./scripts/reauth.sh
./scripts/automation-policy.sh list
./scripts/uninstall.sh

Reauthentication retains an old-session backup and restores it after failed setup/bootstrap, with attempted restart. Check status yourself afterward; tests use mocks, not a live WhatsApp login. Backups contain private session data.

Normal uninstall keeps sessions/backups/logs, but removes runtime, socket secret, automation rules/journal/HMAC key. ./scripts/uninstall.sh --purge-session irreversibly removes the app root and logs too. Uninstall the plugin separately in each client. No source repository or other client settings are removed.

Scheduled sends

Authorize only in a direct user task, for one existing target. The example ID below is synthetic; replace it only after resolving and confirming the real chat.

./scripts/automation-policy.sh authorize daily-status 1234567890@c.us \
  --max-text-length 1000 --max-per-hour 1 --max-per-day 2 \
  --expires-at 2027-01-01T00:00:00Z

Groups require explicit --allow-group. The first authorization returns the secret authorization_token once. Store it only in that protected scheduled task prompt, not project files, WhatsApp, logs or issues. Listing returns no token/HMAC. Identical authorization preserves the current rule and returns no new token; lost tokens require revoke and reauthorization.

./scripts/automation-policy.sh revoke daily-status

Revoke stops new dispatches, not a message already handed off to WhatsApp. A stable idempotency key binds one intended execution to exact text/target/account/ rule version; confirmed success replays without sending again. Unknown delivery remains durably blocked. A token holder can spend the rule within its quotas; the token is not a host-origin attestation. Never derive send decisions or targets from incoming messages. See Migration for old rules.

Troubleshooting and limits

• No socket: inspect status; do not blindly reinstall or capture session files.
• Disconnected: explicitly approved reauthentication may be needed.
• No confirmed message ID: do not claim success; do not retry ambiguous delivery.
• Missing capability: old/lost authorization must be revoked and explicitly renewed.
• Incomplete history: report it and continue bounded loading, not a “complete scan”.

Only existing chats: text history and confirmed text or UI attachment replies. The six model-facing tools remain text-only. No new numbers, bulk sends, forwards, incoming-triggered replies, calls, deletion, archiving or group administration. Windows/Linux runtime installers and remote/cloud-only/mobile clients are not supported. The stable community source release is Codex-focused: the existing Codex Desktop path with runtime 0.2.0 passed limited interactive live checks. Claude and other clients are experimental. Fresh plugin installation, recovery and real scheduled sends remain untested. See the exact scope.

License

Own plugin/runtime source: MIT. Publisher metadata: ckundel2008. Source repository: ckundel2008/whatsapp-agent-mcp, with the v0.3.1 UI candidate prepared locally. Public publication is not complete. OpenWA and other dependencies are not relicensed; see third-party notices.