Dev tool that writes scalable apps from scratch while the developer oversees the implementation
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 
Go to file
Peter Steinberger d2da305190 feat: fallback elevated allowlist to discord dms 11 months ago
.github/workflows CI: split macOS/android checks 11 months ago
Peekaboo@b69e4e8dc0 chore: bump Peekaboo submodule 11 months ago
Swabble chore(swift): update Swabble package lock 11 months ago
apps fix(macos): bridge wizard option values 11 months ago
assets style: lighten DMG background for label contrast 11 months ago
docs feat: fallback elevated allowlist to discord dms 11 months ago
patches fix: harden block stream dedupe 11 months ago
scripts build: add pkg-config + libasound2-dev to sandbox image 11 months ago
skills feat: add Notion API skill 11 months ago
src feat: fallback elevated allowlist to discord dms 11 months ago
test chore: fix lint formatting 11 months ago
ui feat: add elevated bash mode 11 months ago
vendor/a2ui fix: restore build after deps update 11 months ago
.dockerignore Docker: add root-level setup 11 months ago
.env.example Add warelay CLI with Twilio webhook support 12 months ago
.gitignore Discord: update UIs to use the new config 11 months ago
.gitmodules fix(skills/local-places): copy files instead of submodule 11 months ago
.npmrc feat: add bash pty diagnostics 11 months ago
.swiftformat feat(discovery): bonjour beacons + bridge presence 11 months ago
.swiftlint.yml chore: align lint/format configs with peekaboo defaults 12 months ago
AGENTS.md Update connections UIs 11 months ago
CHANGELOG.md docs: update changelog for #166 11 months ago
CLAUDE.md Document exclamation mark escaping workaround for Claude Code 12 months ago
CONTRIBUTING.md docs: add CONTRIBUTING.md with maintainers and guidelines 11 months ago
Dockerfile Docker: add root-level setup 11 months ago
Dockerfile.sandbox feat: add per-session agent sandbox 11 months ago
Dockerfile.sandbox-browser feat: add sandbox browser support 11 months ago
LICENSE Initial commit 12 months ago
README-header.png docs: add README header image 12 months ago
README.md docs: clarify personal vs private in README (#125) 11 months ago
appcast.xml chore: update appcast and TUI streaming handling 11 months ago
biome.json chore: add oxlint type-aware lint 11 months ago
docker-compose.yml Docker: add root-level setup 11 months ago
docker-setup.sh Docker: add root-level setup 11 months ago
package.json docs: migrate Mintlify config 11 months ago
pnpm-lock.yaml refactor: remove bash pty mode 11 months ago
pnpm-workspace.yaml fix: enable lmstudio responses and drop think tags 11 months ago
tsconfig.json web: add heartbeat and bounded reconnect tuning 12 months ago
vitest.config.ts test: isolate vitest home 11 months ago
vitest.e2e.config.ts test(gateway): add multi-instance e2e suite 11 months ago

README.md

🦞 CLAWDIS — Personal AI Assistant

CLAWDIS

EXFOLIATE! EXFOLIATE!

CI status GitHub release Discord MIT License

Clawdis is a personal AI assistant you run on your own devices. It answers you on the surfaces you already use (WhatsApp, Telegram, Discord, iMessage, WebChat), can speak and listen on macOS/iOS, 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, and always-on, this is it.

Website: https://clawd.me · Docs: docs/index.md · FAQ: docs/faq.md · Wizard: docs/wizard.md · Docker (optional): docs/docker.md · Discord: https://discord.gg/clawd

Preferred setup: run the onboarding wizard (clawdis onboard). It walks through gateway, workspace, providers, and skills. The CLI wizard is the recommended path and works on macOS, Windows, and Linux.

Using Claude Pro/Max subscription? See docs/onboarding.md for the Anthropic OAuth setup.

Your surfaces
   │
   ▼
┌───────────────────────────────┐
│            Gateway            │  ws://127.0.0.1:18789
│       (control plane)         │  tcp://0.0.0.0:18790 (optional Bridge)
└──────────────┬────────────────┘
               │
               ├─ Pi agent (RPC)
               ├─ CLI (clawdis …)
               ├─ WebChat (browser)
               ├─ macOS app (Clawdis.app)
               └─ iOS node (Canvas + voice)

What Clawdis does

  • Personal assistant — one user, one identity, one memory surface.
  • Multi-surface inbox — WhatsApp, Telegram, Discord, iMessage, WebChat, macOS, iOS. Signal support via signal-cli (see docs/signal.md). iMessage uses imsg (see docs/imessage.md).
  • Voice wake + push-to-talk — local speech recognition on macOS/iOS.
  • Canvas — a live visual workspace you can drive from the agent.
  • Automation-ready — browser control, media handling, and tool streaming.
  • Local-first control plane — the Gateway owns state, everything else connects.
  • Group chats — mention-based by default, /activation always|mention per group (owner-only).
  • Nix mode — opt-in declarative config + read-only UI when CLAWDIS_NIX_MODE=1.

How it works (short)

  • Gateway is the single source of truth for sessions/providers.
  • Loopback-first: ws://127.0.0.1:18789 by default.
  • Bridge (optional) exposes a paired-node port for iOS/Android.
  • Agent runtime is Pi in RPC mode.

Quick start (from source)

Runtime: Node ≥22 + pnpm.

pnpm install
pnpm build
pnpm ui:build

# Recommended: run the onboarding wizard
pnpm clawdis onboard

# Link WhatsApp (stores creds in ~/.clawdis/credentials)
pnpm clawdis login

# Start the gateway
pnpm clawdis gateway --port 18789 --verbose

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

# Send a message
pnpm clawdis send --to +1234567890 --message "Hello from Clawdis"

# Talk to the assistant (optionally deliver back to WhatsApp/Telegram/Discord)
pnpm clawdis agent --message "Ship checklist" --thinking high

If you run from source, prefer pnpm clawdis … (not global clawdis).

Chat commands

Send these in WhatsApp/Telegram/WebChat (group commands are owner-only):

  • /status — health + session info (group shows activation mode)
  • /new or /reset — reset the session
  • /think <level> — off|minimal|low|medium|high
  • /verbose on|off
  • /restart — restart the gateway (owner-only in groups)
  • /activation mention|always — group activation toggle (groups only)

Architecture

TypeScript Gateway (src/gateway/server.ts)

  • Single HTTP+WS server on ws://127.0.0.1:18789 (bind policy: loopback/lan/tailnet/auto). The first frame must be connect; AJV validates frames against TypeBox schemas (src/gateway/protocol).
  • Single source of truth for sessions, providers, cron, voice wake, and presence. Methods cover send, agent, chat.*, sessions.*, config.*, cron.*, voicewake.*, node.*, system-*, wake.
  • Events + snapshot: handshake returns a snapshot (presence/health) and declares event types; runtime events include agent, chat, presence, tick, health, heartbeat, cron, node.pair.*, voicewake.changed, shutdown.
  • Idempotency & safety: send/agent/chat.send require idempotency keys with a TTL cache (5 min, cap 1000) to avoid double‑sends on reconnects; payload sizes are capped per connection.
  • Bridge for nodes: optional TCP bridge (src/infra/bridge/server.ts) is newline‑delimited JSON frames (hello, pairing, RPC, invoke); node connect/disconnect is surfaced into presence.
  • Control UI + Canvas Host: HTTP serves Control UI assets (default /, optional base path) and can host a live‑reload Canvas host for nodes (src/canvas-host/server.ts), injecting the A2UI postMessage bridge.

iOS app (apps/ios)

  • Discovery + pairing: Bonjour discovery via BridgeDiscoveryModel (NWBrowser). BridgeConnectionController auto‑connects using Keychain token or allows manual host/port.
  • Node runtime: BridgeSession (actor) maintains the NWConnection, hello handshake, ping/pong, RPC requests, and invoke callbacks.
  • Capabilities + commands: advertises canvas, screen, camera, voiceWake (settings‑driven) and executes canvas.*, canvas.a2ui.*, camera.*, screen.record (NodeAppModel.handleInvoke).
  • Canvas: WKWebView with bundled Canvas scaffold + A2UI, JS eval, snapshot capture, and clawdis:// deep‑link interception (ScreenController).
  • Voice + deep links: voice wake sends voice.transcript events; clawdis://agent links emit agent.request. Voice wake triggers sync via voicewake.get + voicewake.changed.

Companion apps

The macOS app is critical: it runs the menu‑bar control plane, owns local permissions (TCC), hosts Voice Wake, exposes WebChat/debug tools, and coordinates local/remote gateway mode. Most “assistant” UX lives here.

macOS (Clawdis.app)

  • Menu bar control for the Gateway and health.
  • Voice Wake + push-to-talk overlay.
  • WebChat + debug tools.
  • Remote gateway control over SSH.

Build/run: ./scripts/restart-mac.sh (packages + launches).

iOS node (internal)

  • Pairs as a node via the Bridge.
  • Voice trigger forwarding + Canvas surface.
  • Controlled via clawdis nodes ….

Runbook: docs/ios/connect.md.

Android node (internal)

  • Pairs via the same Bridge + pairing flow as iOS.
  • Exposes Canvas, Camera, and Screen capture commands.
  • Runbook: docs/android/connect.md.

Agent workspace + skills

  • Workspace root: ~/clawd (configurable via agent.workspace).
  • Injected prompt files: AGENTS.md, SOUL.md, TOOLS.md.
  • Skills: ~/clawd/skills/<skill>/SKILL.md.

Configuration

Minimal ~/.clawdis/clawdis.json:

{
  whatsapp: {
    allowFrom: ["+1234567890"]
  }
}

WhatsApp

  • Link the device: pnpm clawdis login (stores creds in ~/.clawdis/credentials).
  • Allowlist who can talk to the assistant via whatsapp.allowFrom.

Telegram

  • Set TELEGRAM_BOT_TOKEN or telegram.botToken (env wins).
  • Optional: set telegram.groups (with telegram.groups."*".requireMention), telegram.allowFrom, or telegram.webhookUrl as needed.
{
  telegram: {
    botToken: "123456:ABCDEF"
  }
}

Discord

  • Set DISCORD_BOT_TOKEN or discord.token (env wins).
  • Optional: set discord.slashCommand, discord.dm.allowFrom, discord.guilds, or discord.mediaMaxMb as needed.
{
  discord: {
    token: "1234abcd"
  }
}

Browser control (optional):

{
  browser: {
    enabled: true,
    controlUrl: "http://127.0.0.1:18791",
    color: "#FF4500"
  }
}

Docs

Email hooks (Gmail)

clawdis hooks gmail setup --account you@gmail.com
clawdis hooks gmail run

Contributing

See CONTRIBUTING.md for guidelines, maintainers, and how to submit PRs.

AI/vibe-coded PRs welcome! 🤖

Clawd

Clawdis was built for Clawd, a space lobster AI assistant.