🦞 hmm-whatsstatus

Local-first personal AI agent gateway for 20+ messaging platforms.

hmm-whatsstatus runs on your own machine (macOS, Linux, Windows) as a TypeScript/Node.js service. It acts as a unified inbox and execution engine — connect all your messaging platforms, route messages through AI agents, and give those agents tools to execute commands, browse the web, draw on canvas, and more.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    hmm-whatsstatus Gateway                          │
│                                                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────────┐ │
│  │ Discord  │  │ Telegram │  │  Slack   │  │  WhatsApp  │ │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └─────┬──────┘ │
│       │              │             │              │         │
│  ┌────┴──────────────┴─────────────┴──────────────┴──────┐ │
│  │              Message Routing Engine                     │ │
│  │  • Channel + Sender → Agent binding lookup             │ │
│  │  • Session key derivation                              │ │
│  │  • Mention gating & allowlist checks                   │ │
│  └────────────────────────┬───────────────────────────────┘ │
│                           │                                  │
│  ┌────────────────────────┴───────────────────────────────┐ │
│  │              Agent Execution Pipeline                   │ │
│  │  • Load JSONL transcript                               │ │
│  │  • Compaction checkpoints                              │ │
│  │  • LLM completion with fallback chain                  │ │
│  │  • Tool execution with approval gating                 │ │
│  │  • Stream tokens back to channel                       │ │
│  └────────────────────────┬───────────────────────────────┘ │
│                           │                                  │
│  ┌────────────────────────┴───────────────────────────────┐ │
│  │  HTTP API  │  WebSocket  │  Webhooks  │  Control UI    │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

Install

npm (recommended)

npm install -g mxclaw@latest

# Run the interactive setup wizard
mxclaw onboard

# Validate your configuration
mxclaw doctor

# Start the gateway
mxclaw gateway

From source

git clone https://github.com/mxclaw/mxclaw.git
cd mxclaw
pnpm install
pnpm build

# Run setup wizard
node dist/cli.mjs onboard

# Start the gateway
node dist/cli.mjs gateway

CLI Commands

Command	Description
mxclaw gateway	Start the gateway server
mxclaw onboard	Interactive setup wizard (providers, channels, agents, daemon)
mxclaw onboard --install-daemon	Install auto-start daemon (launchd/systemd)
mxclaw onboard --uninstall-daemon	Remove auto-start daemon
mxclaw onboard --status	Check daemon status
mxclaw doctor	Diagnose config and environment
mxclaw channels --list	List configured channels
mxclaw channels --add discord	Add a new channel
mxclaw models --list	List configured agents
mxclaw sessions --list	List chat sessions
mxclaw auth --list-devices	List paired devices
mxclaw bind --list	List channel bindings
mxclaw config --show	Show current config
mxclaw runner	Quick start — setup + doctor + gateway in one command

Configuration

Config lives at ~/.mxclaw/mxclaw.json:

{
  "version": 1,
  "gateway": { "host": "127.0.0.1", "port": 18700 },
  "agents": {
    "default": {
      "id": "default",
      "name": "Default Agent",
      "model": { "provider": "openai", "model": "gpt-4o" },
      "fallbackChain": [
        { "provider": "anthropic", "model": "claude-sonnet-4-20250514" },
        { "provider": "groq", "model": "llama-3.3-70b-versatile" }
      ],
      "tools": {
        "bash": { "enabled": true, "approval": "always-require-approval" },
        "fileRead": { "enabled": true, "approval": "owner-only" }
      }
    }
  },
  "defaultAgentId": "default",
  "channels": {
    "discord-1": {
      "id": "discord-1",
      "type": "discord",
      "enabled": true,
      "credentials": { "token": "YOUR_BOT_TOKEN" }
    }
  },
  "bindings": [
    { "channelId": "discord-1", "agentId": "default" }
  ]
}

Supported Channels (14)

Channel	Protocol	Status
Discord	WebSocket Intents	✅
Telegram	Bot API (polling)	✅
Slack	Events API + Socket Mode	✅
WhatsApp	Baileys WebSocket	✅
Matrix	Matrix SDK + E2EE	✅
Signal	signal-cli REST API	✅
iMessage	BlueBubbles API	✅
Feishu/Lark	Open API	✅
IRC	Raw TCP socket	✅
Mattermost	WebSocket API	✅
Google Chat	REST API	✅
Microsoft Teams	Bot Framework	✅
Nextcloud Talk	OCS API	✅
LINE	Messaging API	✅

Supported LLM Providers (17)

Provider	Type	Streaming
OpenAI	Cloud	✅
Anthropic	Cloud	✅
Google Gemini	Cloud	✅
Groq	Cloud	✅
DeepSeek	Cloud	✅
LM Studio	Local	✅
Ollama	Local	✅
Together AI	Cloud	✅
Fireworks AI	Cloud	✅
Replicate	Cloud	✅
Cohere	Cloud	✅
Mistral	Cloud	✅
Perplexity	Cloud	✅
xAI (Grok)	Cloud	✅
AWS Bedrock	Cloud	✅
Azure OpenAI	Cloud	✅
Cloudflare Workers AI	Edge	✅

Agent Tools

Tool	Description	Default Approval
bash	Shell command execution	always-require-approval
browser	Chrome CDP browser control	always-require-approval
canvas	A2UI JSON canvas drawing	owner-only
cron	Schedule recurring tasks	always-require-approval
session_spawn	Spawn sub-agent sessions	owner-only
image_gen	AI image generation	always-require-approval
file_read	Read files from workspace	owner-only
file_write	Write files to workspace	always-require-approval

Security Model

• Pairing codes: Unknown senders get a 6-character code, approved via control UI
• Allowlists: Per-channel sender allowlists
• Mention gating: In group chats, only respond when @mentioned
• Device pairing: Mobile/web clients pair via QR code or shared token
• Token rotation: Device tokens rotate on each WebSocket connect
• Approval modes: always-require-approval, owner-only, yolo
• Sandboxing: Docker or SSH sandbox for untrusted agents

Failure Handling

• Channel disconnect: Outbound replies queued, retried on reconnect
• Missing transcript: Fresh session started automatically
• Corrupted config: Falls back to last-known-good snapshot
• Plugin load errors: Skipped plugin, surfaced in /status
• Tool timeouts: 30s timeout, escalated to user with retry option
• Provider failures: Automatic fallback chain with exponential backoff (max 3 retries)

Project Structure

hmm-whatsstatus/
├── packages/
│   ├── core/              # Types, config schema (Zod), utilities
│   ├── cli/               # CLI entry point (commander)
│   ├── gateway/           # HTTP + WebSocket server, routing engine
│   ├── plugin-system/     # Plugin loader, manifest system
│   ├── storage/           # LanceDB + SQLite + JSONL storage
│   ├── security/          # Pairing, allowlists, mention gating
│   ├── tools/             # Agent tools (bash, browser, canvas, etc.)
│   ├── logging/           # Subsystem-tagged logging + OTel
│   ├── voice/             # Voice integration (OpenAI, Gemini, ElevenLabs)
│   ├── control-ui/        # React/Vite control dashboard
│   ├── channel-*/         # 14 channel plugins
│   └── provider-*/        # 17 provider plugins
├── apps/
│   ├── macos/             # Swift macOS menu bar app spec
│   ├── ios/               # Swift iOS app spec
│   └── android/           # Kotlin Android app spec
├── pnpm-workspace.yaml
├── tsconfig.base.json
└── package.json

API Endpoints

Method	Path	Description
GET	/health	Health check
GET	/status	Full gateway status
GET	/api/config	Get config (redacted)
PUT	/api/config	Update config (hot-reload)
GET	/api/sessions	List sessions
GET	/api/session/transcript	Get session transcript
POST	/api/session/reset	Reset a session
GET	/api/approvals	List pending approvals
POST	/api/approval/resolve	Approve/deny
POST	/api/chat/send	Send a chat message
POST	/api/pairing/generate	Generate pairing code
POST	/api/pairing/validate	Validate pairing code
POST	/api/devices/pair	Pair a device
POST	/gateway/webhook/*	Inbound webhooks

WebSocket Protocol

Clients connect to ws://127.0.0.1:18700 and authenticate with a device token.

Client → Server: auth, chat:send, chat:approve, canvas:event, voice:start, voice:stop, voice:audio, presence:update, ping

Server → Client: auth:ok, auth:error, chat:token, chat:done, chat:error, approval:required, canvas:update, voice:token, voice:error, presence:update, status:update, pong, error

License

MIT