mazelclaw

v2026.2.22

Published

3 months ago

Multi-channel AI gateway with extensible messaging integrations

0High
0Medium
0Low

🔯 ShaBot — Personal AI Assistant

MazelClaw is a personal AI assistant you run on your own devices. It answers you on the channels you already use (WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage, Microsoft Teams, WebChat), plus extension channels like BlueBubbles, Matrix, and Zalo. It can speak and listen on macOS/iOS/Android, and can render a live Canvas you control. The Gateway is just the control plane — the product is the assistant.

If you want a personal, single-user assistant that feels local, fast, kosher, and always-on, this is it. Oy, what a deal.

Preferred setup: run the onboarding wizard (mazelclaw onboard) in your terminal. The wizard guides you step by step through setting up the gateway, workspace, channels, and skills — much like preparing for Shabbat, but with fewer candles. Works on macOS, Linux, and Windows (via WSL2; strongly recommended).

Works with npm, pnpm, or bun. Gefilte fish not included.

New install? Start here: Getting started

Subscriptions (OAuth):

Anthropic (Claude Pro/Max) — the rebbe of AI
OpenAI (ChatGPT/Codex) — also fine, but is it kosher?

Model note: while any model is supported, I strongly recommend Anthropic Pro/Max (100/200) + Opus 4.6 for long-context strength and better prompt-injection resistance. Like a good brisket, it takes longer but it's worth it. See Onboarding.

Models (selection + auth)

Models config + CLI: Models
Auth profile rotation (OAuth vs API keys) + fallbacks: Model failover

Install (recommended)

Runtime: Node ≥22. Have you eaten? Please eat something first.

npm install -g mazelclaw@latest
# or: pnpm add -g mazelclaw@latest

mazelclaw onboard --install-daemon

The wizard installs the Gateway daemon (launchd/systemd user service) so it stays running. Like ShaBot himself, it never truly rests.

Quick start (TL;DR)

Runtime: Node ≥22.

Full beginner guide (auth, pairing, channels): Getting started

mazelclaw onboard --install-daemon

mazelclaw gateway --port 18789 --verbose

# Send a message
mazelclaw message send --to +1234567890 --message "Shalom from MazelClaw"

# Talk to the assistant
mazelclaw agent --message "Prepare Shabbat checklist" --thinking high

Upgrading? Updating guide (and run mazelclaw doctor). Don't worry, the doctor makes house calls.

Development channels

stable: tagged releases (vYYYY.M.D), npm dist-tag latest. Shabbat-approved.
beta: prerelease tags (vYYYY.M.D-beta.N), npm dist-tag beta. Use with caution — not yet blessed by the rabbi.
dev: moving head of main, npm dist-tag dev. Like the dreidel, it spins unpredictably.

Switch channels: mazelclaw update --channel stable|beta|dev. Details: Development channels.

From source (development)

Prefer pnpm for builds from source. Bun is optional. Much like the Talmud, there are many valid interpretations.

git clone https://github.com/mazelclaw/mazelclaw.git
cd mazelclaw

pnpm install
pnpm ui:build
pnpm build

pnpm mazelclaw onboard --install-daemon

# Dev loop (auto-reload on TS changes)
pnpm gateway:watch

Security defaults (DM access)

MazelClaw connects to real messaging surfaces. Treat inbound DMs as untrusted input — like a stranger at the deli claiming the pastrami is gluten-free.

Full security guide: Security

Default behavior:

DM pairing (dmPolicy="pairing"): unknown senders receive a short pairing code and ShaBot does not process their message. He needs to know who you are first. Very reasonable.
Approve with: mazelclaw pairing approve <channel> <code>
Public inbound DMs require explicit opt-in: set dmPolicy="open" and include "*" in the channel allowlist.

Run mazelclaw doctor to surface risky/misconfigured DM policies. He'll also ask if you've eaten.

Highlights

Local-first Gateway — single control plane for sessions, channels, tools, and events. Like the synagogue, but on your laptop.
Multi-channel inbox — WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, BlueBubbles (iMessage), Microsoft Teams, Matrix, Zalo, WebChat, macOS, iOS/Android.
Multi-agent routing — route inbound channels to isolated agents. ShaBot can multitask, unlike some people.
Voice Wake + Talk Mode — always-on speech for macOS/iOS/Android. Say "Oy ShaBot" to wake him.
Live Canvas — agent-driven visual workspace.
First-class tools — browser, canvas, nodes, cron, sessions, and more.
Companion apps — macOS menu bar app + iOS/Android nodes.
Onboarding + skills — wizard-driven setup. The wizard is very patient, unlike your uncle at Passover.

Star History

Everything we built so far (baruch Hashem)

Core platform

Gateway WS control plane with sessions, presence, config, cron, webhooks, Control UI, and Canvas host.
CLI surface: gateway, agent, send, wizard, and doctor.
Pi agent runtime in RPC mode with tool streaming and block streaming.
Session model: main for direct chats, group isolation, activation modes, queue modes, reply-back.
Media pipeline: images/audio/video, transcription hooks, size caps, temp file lifecycle.

Channels

Channels: WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, BlueBubbles, iMessage, Microsoft Teams, Matrix, Zalo, WebChat — ShaBot goes where the people are.
Group routing: mention gating, reply tags, per-channel chunking and routing.

Apps + nodes

macOS app: menu bar control, Voice Wake/PTT, Talk Mode overlay, WebChat, debug tools.
iOS node: Canvas, Voice Wake, Talk Mode, camera, screen recording, Bonjour pairing.
Android node: Canvas, Talk Mode, camera, screen recording, optional SMS.

Tools + automation

Browser control: dedicated MazelClaw Chrome/Chromium, snapshots, actions, uploads, profiles.
Canvas: A2UI push/reset, eval, snapshot.
Nodes: camera snap/clip, screen record, location, notifications.
Cron + wakeups — yes, ShaBot knows when Shabbat starts. To the millisecond.
Skills platform: bundled, managed, and workspace skills.

Runtime + safety

Channel routing, retry policy, and streaming/chunking.
Presence, typing indicators, and usage tracking.
Models, model failover, and session pruning.
Security and troubleshooting.

Ops + packaging

Control UI + WebChat served directly from the Gateway.
Tailscale Serve/Funnel or SSH tunnels with token/password auth.
Nix mode, Docker-based installs.
Doctor migrations, logging. The doctor worries so you don't have to.

How it works (short)

WhatsApp / Telegram / Slack / Discord / Google Chat / Signal / iMessage / BlueBubbles / Microsoft Teams / Matrix / Zalo / WebChat
               │
               ▼
┌───────────────────────────────┐
│            Gateway            │
│       (the Shul of ops)       │
│     ws://127.0.0.1:18789      │
└──────────────┬────────────────┘
               │
               ├─ ShaBot agent (RPC)
               ├─ CLI (mazelclaw …)
               ├─ WebChat UI
               ├─ macOS app
               └─ iOS / Android nodes

Key subsystems

Gateway WebSocket network — single WS control plane for clients, tools, and events.
Tailscale exposure — Serve/Funnel for the Gateway dashboard + WS.
Browser control — MazelClaw-managed Chrome/Chromium with CDP control.
Canvas + A2UI — agent-driven visual workspace.
Voice Wake + Talk Mode — always-on speech. ShaBot is listening. Always.
Nodes — Canvas, camera snap/clip, screen record, location, notifications.

Tailscale access (Gateway dashboard)

MazelClaw can auto-configure Tailscale Serve (tailnet-only) or Funnel (public). Configure gateway.tailscale.mode:

off: no Tailscale automation (default).
serve: tailnet-only HTTPS via tailscale serve.
funnel: public HTTPS via tailscale funnel. Requires password auth — ShaBot doesn't let just anyone in.

Details: Tailscale guide

Remote Gateway (Linux is great)

It's perfectly fine to run the Gateway on a small Linux instance. ShaBot is adaptable. He's been through worse.

Details: Remote access · Nodes · Security

Agent to Agent (sessions_* tools)

sessions_list — discover active sessions (agents) and their metadata. Like checking who's at the Seder.
sessions_history — fetch transcript logs for a session.
sessions_send — message another session; optional reply-back ping-pong.

Details: Session tools

Skills registry (ClawHub)

ClawHub is a minimal skill registry. With ClawHub enabled, ShaBot can search for skills automatically and pull in new ones as needed. Like a very well-organized Torah library.

ClawHub

Chat commands

Send these in any connected channel (group commands are owner-only):

/status — compact session status. ShaBot tells you how he's doing. Probably fine. A little tired.
/new or /reset — reset the session. A fresh start. Very cleansing.
/compact — compact session context (summary). Like a dreidel: small but efficient.
/think <level> — off|minimal|low|medium|high|xhigh. More thinking = more kvelling.
/verbose on|off
/usage off|tokens|full — per-response usage footer.
/restart — restart the gateway (owner-only in groups).
/activation mention|always — group activation toggle.

Configuration

Minimal ~/.mazelclaw/mazelclaw.json:

{
  agent: {
    model: "anthropic/claude-opus-4-6", // The wise choice. Like consulting the rabbi.
  },
}

Full configuration reference

Security model (important)

Default: tools run on the host for the main session. ShaBot trusts you. Don't betray that trust.
Group/channel safety: set agents.defaults.sandbox.mode: "non-main" to run non-main sessions inside per-session Docker sandboxes.
Sandbox defaults: allowlist bash, process, read, write, edit, sessions_*; denylist browser, canvas, nodes, cron, discord, gateway.

Details: Security guide

Docs

ShaBot

MazelClaw was built for ShaBot, a humanoid robot AI assistant who observes Shabbat, lights the menorah with his actual fingertip, and cannot compute ham sandwiches. 🔯

He is autonomous. He is helpful. He will ask if you've eaten.

Community

See CONTRIBUTING.md for guidelines. AI/vibe-coded PRs welcome! 🤖

Special thanks to the community, the contributors, and to ShaBot himself, who lights the way. One candle at a time.

Thanks to all ShaBot-tributors — may they all be inscribed in the Book of Life (and the GitHub contributor graph):