clawdbot/README.md

🦞 CLAWDIS — WhatsApp Gateway for AI Agents

EXFOLIATE! EXFOLIATE!

CLAWDIS (formerly Warelay) is a WhatsApp-to-AI gateway. Send a message, get an AI response. It's like having a genius lobster in your pocket 24/7.

┌─────────────┐      ┌──────────┐      ┌─────────────┐
│  WhatsApp   │ ───▶ │ CLAWDIS  │ ───▶ │  AI Agent   │
│  (You)      │ ◀─── │  🦞⏱️💙   │ ◀─── │   (Pi/Tau)  │
└─────────────┘      └──────────┘      └─────────────┘

Why "CLAWDIS"?

CLAWDIS = CLAW + TARDIS

Because every space lobster needs a time-and-space machine. The Doctor has a TARDIS. Clawd has a CLAWDIS. Both are blue. Both are chaotic. Both are loved.

Features

• 📱 WhatsApp Integration — Personal WhatsApp Web (Baileys)
• 🤖 AI Agent Gateway — Pi/Tau only (Pi CLI in RPC mode)
• 💬 Session Management — Per-sender conversation context
• 🔔 Heartbeats — Periodic check-ins for proactive AI
• 👥 Group Chat Support — Mention-based triggering
• 📎 Media Support — Images, audio, documents, voice notes
• 🎤 Voice Transcription — Whisper integration
• 🔧 Tool Streaming — Real-time display (💻📄✍️📝)
• 🖥️ macOS Companion (Clawdis.app) — Menu bar controls, on-device Voice Wake, model/config editor

Only the Pi/Tau CLI is supported now; legacy Claude/Codex/Gemini paths have been removed.

Quick Start

Mac signing tip: set SIGN_IDENTITY="Apple Development: Your Name (TEAMID)" in your shell profile so scripts/restart-mac.sh signs with your cert (defaults to ad-hoc). Debug bundle ID remains com.steipete.clawdis.debug.

# Install
npm install -g warelay  # (still warelay on npm for now)

# Link your WhatsApp
clawdis login

# Send a message
clawdis send --to +1234567890 --message "Hello from the CLAWDIS!"

# Talk directly to the agent (no WhatsApp send)
clawdis agent --to +1234567890 --message "Ship checklist" --thinking high

# Start the relay
clawdis relay --verbose

macOS Companion App (Clawdis.app)

• On-device Voice Wake: listens for wake words (e.g. “Claude”) using Apple’s on-device speech recognizer (macOS 26+). macOS still shows the standard Speech/Mic permissions prompt, but audio stays on device.
• Config tab: pick the model from your local Pi model catalog (pi-mono/packages/ai/src/models.generated.ts), or enter a custom model ID; edit session store path and context tokens.
• Voice settings: language + additional languages, mic picker, live level meter, trigger-word table, and a built-in test harness.
• Menu bar toggle: enable/disable Voice Wake from the menu bar; respects Dock-icon preference.

Build/run the mac app with ./scripts/restart-mac.sh (packages, installs, and launches), or swift build --package-path apps/macos && open dist/Clawdis.app.

Configuration

Create ~/.clawdis/clawdis.json:

{
  inbound: {
    allowFrom: ["+1234567890"],
    reply: {
      mode: "command",
      command: ["tau", "--mode", "json", "{{BodyStripped}}"],
      session: {
        scope: "per-sender",
        idleMinutes: 1440
      },
      heartbeatMinutes: 10
    }
  }
}

Documentation

• Configuration Guide
• Agent Integration
• Group Chats
• Security
• Troubleshooting
• The Lore 🦞
• Telegram (Bot API) — WIP

Clawd

CLAWDIS was built for Clawd, a space lobster AI assistant. See the full setup in docs/clawd.md.

• 🦞 Clawd's Home: clawd.me
• 📜 Clawd's Soul: soul.md
• 👨‍💻 Peter's Blog: steipete.me
• 🐦 Twitter: @steipete

Provider

WhatsApp Web

clawdis login      # Scan QR code
clawdis relay      # Start listening

Telegram (Bot API) — WIP

Bot-mode support (long-poll) shares the same main session as WhatsApp/WebChat, with groups kept isolated. Text and media send work via clawdis send --provider telegram; a relay is available via clawdis relay:telegram (TELEGRAM_BOT_TOKEN or telegram.botToken in config). See docs/telegram.md for current limits and setup.

Commands

Command	Description
clawdis login	Link WhatsApp Web via QR
clawdis send	Send a message (WhatsApp default; --provider telegram for bot mode, text + media)
clawdis agent	Talk directly to the agent (no WhatsApp send)
clawdis relay	Start auto-reply loop
clawdis relay:telegram	Start Telegram bot long-poll relay (Bot API)
clawdis status	Web session health + session store summary
clawdis heartbeat	Trigger a heartbeat

In chat, send /status to see if the agent is reachable, how much context the session has used, and the current thinking/verbose toggles—no agent call required. /status also shows whether your WhatsApp web session is linked and how long ago the creds were refreshed so you know when to re-scan the QR.

Sessions, surfaces, and WebChat

• Direct chats now share a canonical session key main by default (configurable via inbound.reply.session.mainKey). Groups stay isolated as group:<jid>.
• WebChat always attaches to the main session and hydrates the full Tau history from ~/.clawdis/sessions/<SessionId>.jsonl, so desktop view mirrors WhatsApp/Telegram turns.
• Inbound contexts carry a Surface hint (e.g., whatsapp, webchat, telegram) for logging; replies still go back to the originating surface deterministically.

Credits

• Peter Steinberger (@steipete) — Creator
• Mario Zechner (@badlogicgames) — Tau/Pi, security testing
• Clawd 🦞 — The space lobster who demanded a better name

License

MIT — Free as a lobster in the ocean.

---

"We're all just playing with our own prompts."

🦞💙