farcasclaudiu/openclaw
1
0
Fork 0
mirror of https://github.com/farcasclaudiu/openclaw.git synced 2026-06-28 13:01:42 +03:00
Code Issues Packages Projects Releases Wiki Activity

chore: rename project to clawdbot

Browse Source
This commit is contained in:
Peter Steinberger
2026-01-04 14:32:47 +00:00
parent d48dc71fa4
commit 246adaa119
841 changed files with 4590 additions and 4328 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/AGENTS.default.md
+16 -16
View File
@@ -1,33 +1,33 @@
---
summary: "Default Clawdis agent instructions and skills roster for the personal assistant setup"
summary: "Default Clawdbot agent instructions and skills roster for the personal assistant setup"
read_when:
- Starting a new Clawdis agent session
- Starting a new Clawdbot agent session
- Enabling or auditing default skills
---
# AGENTS.md — Clawdis Personal Assistant (default)
# AGENTS.md — Clawdbot Personal Assistant (default)
## First run (recommended)
Clawdis uses a dedicated workspace directory for the agent. Default: `~/.clawdis/workspace`.
Clawdbot uses a dedicated workspace directory for the agent. Default: `~/.clawdbot/workspace`.
1) Create the workspace (if it doesn’t already exist):
```bash
mkdir -p ~/.clawdis/workspace
mkdir -p ~/.clawdbot/workspace
```
2) Copy the default workspace templates into the workspace:
```bash
cp docs/templates/AGENTS.md ~/.clawdis/workspace/AGENTS.md
cp docs/templates/SOUL.md ~/.clawdis/workspace/SOUL.md
cp docs/templates/TOOLS.md ~/.clawdis/workspace/TOOLS.md
cp docs/templates/AGENTS.md ~/.clawdbot/workspace/AGENTS.md
cp docs/templates/SOUL.md ~/.clawdbot/workspace/SOUL.md
cp docs/templates/TOOLS.md ~/.clawdbot/workspace/TOOLS.md
```
3) Optional: if you want the personal assistant skill roster, replace AGENTS.md with this file:
```bash
cp docs/AGENTS.default.md ~/.clawdis/workspace/AGENTS.md
cp docs/AGENTS.default.md ~/.clawdbot/workspace/AGENTS.md
```
4) Optional: choose a different workspace by setting `agent.workspace` (supports `~`):
@@ -73,16 +73,16 @@ cp docs/AGENTS.default.md ~/.clawdis/workspace/AGENTS.md
If you treat this workspace as Clawd’s “memory”, make it a git repo (ideally private) so `AGENTS.md` and your memory files are backed up.
```bash
cd ~/.clawdis/workspace
cd ~/.clawdbot/workspace
git init
git add AGENTS.md
git commit -m "Add Clawd workspace"
# Optional: add a private remote + push
```
## What Clawdis Does
## What Clawdbot Does
- Runs WhatsApp gateway + Pi coding agent so the assistant can read/write chats, fetch context, and run skills via the host Mac.
- macOS app manages permissions (screen recording, notifications, microphone) and exposes the `clawdis` CLI via its bundled binary.
- macOS app manages permissions (screen recording, notifications, microphone) and exposes the `clawdbot` CLI via its bundled binary.
- Direct chats collapse into the shared `main` session by default; groups stay isolated as `surface:group:<id>` (rooms: `surface:channel:<id>`); heartbeats keep background tasks alive.
## Core Skills (enable in Settings → Skills)
@@ -107,10 +107,10 @@ git commit -m "Add Clawd workspace"
- **agent-tools** — Utility toolkit for automations and helper scripts.
## Usage Notes
- Prefer the `clawdis` CLI for scripting; mac app handles permissions.
- Prefer the `clawdbot` CLI for scripting; mac app handles permissions.
- Run installs from the Skills tab; it hides the button if a binary is already present.
- Keep heartbeats enabled so the assistant can schedule reminders, monitor inboxes, and trigger camera captures.
- Canvas UI runs full-screen with native overlays. Avoid placing critical controls in the top-left/top-right/bottom edges; add explicit gutters in the layout and don’t rely on safe-area insets.
- For browser-driven verification, use `clawdis browser` (tabs/status/screenshot) with the clawd-managed Chrome profile.
- For DOM inspection, use `clawdis browser eval|query|dom|snapshot` (and `--json`/`--out` when you need machine output).
- For interactions, use `clawdis browser click|type|hover|drag|select|upload|press|wait|navigate|back|evaluate|run` (click/type require snapshot refs; use `evaluate` for CSS selectors).
- For browser-driven verification, use `clawdbot browser` (tabs/status/screenshot) with the clawd-managed Chrome profile.
- For DOM inspection, use `clawdbot browser eval|query|dom|snapshot` (and `--json`/`--out` when you need machine output).
- For interactions, use `clawdbot browser click|type|hover|drag|select|upload|press|wait|navigate|back|evaluate|run` (click/type require snapshot refs; use `evaluate` for CSS selectors).
docs/CNAME
+1 -1
View File
@@ -1 +1 @@
clawdis.ai
clawdbot.com
docs/RELEASING.md
+9 -9
View File
@@ -13,7 +13,7 @@ Use `pnpm` (Node 22+) from the repo root. Keep the working tree clean before tag
1) **Version & metadata**
- [ ] Bump `package.json` version (e.g., `1.1.0`).
- [ ] Update CLI/version strings: `src/cli/program.ts` and the Baileys user agent in `src/provider-web.ts`.
- [ ] Confirm package metadata (name, description, repository, keywords, license) and `bin` map points to `dist/index.js` for `clawdis`.
- [ ] Confirm package metadata (name, description, repository, keywords, license) and `bin` map points to `dist/index.js` for `clawdbot`.
- [ ] If dependencies changed, run `pnpm install` so `pnpm-lock.yaml` is current.
2) **Build & artifacts**
@@ -38,27 +38,27 @@ Use `pnpm` (Node 22+) from the repo root. Keep the working tree clean before tag
- [ ] Keep the app zip (and optional dSYM zip) ready to attach to the GitHub release.
- [ ] Follow `docs/mac/release.md` for the exact commands and required env vars.
- `APP_BUILD` must be numeric + monotonic (no `-beta`) so Sparkle compares versions correctly.
- If notarizing, use the `clawdis-notary` keychain profile created from App Store Connect API env vars (see `docs/mac/release.md`).
- If notarizing, use the `clawdbot-notary` keychain profile created from App Store Connect API env vars (see `docs/mac/release.md`).
6) **Publish (npm)**
- [ ] Confirm git status is clean; commit and push as needed.
- [ ] `npm login` (verify 2FA) if needed.
- [ ] `npm publish --access public` (use `--tag beta` for pre-releases).
- [ ] Verify the registry: `npm view clawdis version` and `npx -y clawdis@X.Y.Z --version` (or `--help`).
- [ ] Verify the registry: `npm view clawdbot version` and `npx -y clawdbot@X.Y.Z --version` (or `--help`).
### Troubleshooting (notes from 2.0.0-beta2 release)
- **npm pack/publish hangs or produces huge tarball**: the macOS app bundle in `dist/Clawdis.app` (and release zips) get swept into the package. Fix by whitelisting publish contents via `package.json` `files` (include dist subdirs, docs, skills; exclude app bundles). Confirm with `npm pack --dry-run` that `dist/Clawdis.app` is not listed.
- **npm pack/publish hangs or produces huge tarball**: the macOS app bundle in `dist/Clawdbot.app` (and release zips) get swept into the package. Fix by whitelisting publish contents via `package.json` `files` (include dist subdirs, docs, skills; exclude app bundles). Confirm with `npm pack --dry-run` that `dist/Clawdbot.app` is not listed.
- **npm auth web loop for dist-tags**: use legacy auth to get an OTP prompt:
- `NPM_CONFIG_AUTH_TYPE=legacy npm dist-tag add clawdis@X.Y.Z latest`
- `NPM_CONFIG_AUTH_TYPE=legacy npm dist-tag add clawdbot@X.Y.Z latest`
- **`npx` verification fails with `ECOMPROMISED: Lock compromised`**: retry with a fresh cache:
- `NPM_CONFIG_CACHE=/tmp/npm-cache-$(date +%s) npx -y clawdis@X.Y.Z --version`
- `NPM_CONFIG_CACHE=/tmp/npm-cache-$(date +%s) npx -y clawdbot@X.Y.Z --version`
- **Tag needs repointing after a late fix**: force-update and push the tag, then ensure the GitHub release assets still match:
- `git tag -f vX.Y.Z && git push -f origin vX.Y.Z`
7) **GitHub release + appcast**
- [ ] Tag and push: `git tag vX.Y.Z && git push origin vX.Y.Z` (or `git push --tags`).
- [ ] Create/refresh the GitHub release for `vX.Y.Z` with **title `clawdis X.Y.Z`** (not just the tag); body should inline the product-facing bullets from the changelog (no bare links) **and must not repeat the title inside the body**.
- [ ] Attach artifacts: `npm pack` tarball (optional), `Clawdis-X.Y.Z.zip`, and `Clawdis-X.Y.Z.dSYM.zip` (if generated).
- [ ] Create/refresh the GitHub release for `vX.Y.Z` with **title `clawdbot X.Y.Z`** (not just the tag); body should inline the product-facing bullets from the changelog (no bare links) **and must not repeat the title inside the body**.
- [ ] Attach artifacts: `npm pack` tarball (optional), `Clawdbot-X.Y.Z.zip`, and `Clawdbot-X.Y.Z.dSYM.zip` (if generated).
- [ ] Commit the updated `appcast.xml` and push it (Sparkle feeds from main).
- [ ] From a clean temp directory (no `package.json`), run `npx -y clawdis@X.Y.Z send --help` to confirm install/CLI entrypoints work.
- [ ] From a clean temp directory (no `package.json`), run `npx -y clawdbot@X.Y.Z send --help` to confirm install/CLI entrypoints work.
- [ ] Announce/share release notes.
docs/_config.yml
+2 -2
View File
@@ -1,4 +1,4 @@
title: "CLAWDIS Docs"
title: "CLAWDBOT Docs"
description: "A TypeScript/Node gateway + macOS/iOS companions for WhatsApp (web) and Telegram (bot)."
markdown: kramdown
highlighter: rouge
@@ -35,7 +35,7 @@ nav:
- title: "WebChat"
url: "/webchat.html"
- title: "macOS App"
url: "/clawdis-mac.html"
url: "/clawdbot-mac.html"
- title: "iOS Node"
url: "/ios/connect.html"
- title: "Telegram"
docs/_layouts/default.html
+9 -9
View File
@@ -17,7 +17,7 @@
<script>
(() => {
try {
const stored = localStorage.getItem("clawdis:theme");
const stored = localStorage.getItem("clawdbot:theme");
if (stored === "light" || stored === "dark") document.documentElement.dataset.theme = stored;
} catch {
// ignore
@@ -35,7 +35,7 @@
<header class="shell">
<div class="shell__frame" role="banner">
<div class="shell__titlebar">
<div class="brand" aria-label="CLAWDIS docs terminal">
<div class="brand" aria-label="CLAWDBOT docs terminal">
<img
class="brand__logo"
src="{{ "/assets/pixel-lobster.svg" | relative_url }}"
@@ -45,17 +45,17 @@
decoding="async"
/>
<div class="brand__text">
<div class="brand__name">CLAWDIS</div>
<div class="brand__name">CLAWDBOT</div>
<div class="brand__hint">docs // lobster terminal</div>
</div>
</div>
<div class="titlebar__actions">
<a class="titlebar__cta" href="https://github.com/steipete/clawdis">
<a class="titlebar__cta" href="https://github.com/clawdbot/clawdbot">
<span class="titlebar__cta-label">GitHub</span>
<span class="titlebar__cta-meta">repo</span>
</a>
<a class="titlebar__cta titlebar__cta--accent" href="https://github.com/steipete/clawdis/releases/latest">
<a class="titlebar__cta titlebar__cta--accent" href="https://github.com/clawdbot/clawdbot/releases/latest">
<span class="titlebar__cta-label">Download</span>
<span class="titlebar__cta-meta">latest</span>
</a>
@@ -90,7 +90,7 @@
<main id="content" class="content" role="main">
<div class="terminal">
<div class="terminal__prompt" aria-hidden="true">
<span class="prompt__user">clawd</span>@<span class="prompt__host">clawdis</span>:<span class="prompt__path">~/docs</span>$<span class="prompt__cmd">
<span class="prompt__user">clawd</span>@<span class="prompt__host">clawdbot</span>:<span class="prompt__path">~/docs</span>$<span class="prompt__cmd">
{% if page.url == "/" %}cat index.md{% else %}less {{ page.path }}{% endif %}
</span>
</div>
@@ -116,11 +116,11 @@
<footer class="terminal__footer" role="contentinfo">
<div class="footer__line">
<span class="footer__sig">clawdis.ai</span>
<span class="footer__sig">clawdbot.ai</span>
<span class="footer__sep">·</span>
<a href="https://github.com/steipete/clawdis">source</a>
<a href="https://github.com/clawdbot/clawdbot">source</a>
<span class="footer__sep">·</span>
<a href="https://github.com/steipete/clawdis/releases">releases</a>
<a href="https://github.com/clawdbot/clawdbot/releases">releases</a>
</div>
<div class="footer__hint" aria-hidden="true">
tip: press <kbd>F2</kbd> (Mac: <kbd>fn</kbd>+<kbd>F2</kbd>) to flip
docs/agent-send.md
+3 -3
View File
@@ -1,11 +1,11 @@
---
summary: "Design notes for a direct `clawdis agent` CLI subcommand without WhatsApp delivery"
summary: "Design notes for a direct `clawdbot agent` CLI subcommand without WhatsApp delivery"
read_when:
- Adding or modifying the agent CLI entrypoint
---
# `clawdis agent` (direct-to-agent invocation)
# `clawdbot agent` (direct-to-agent invocation)
`clawdis agent` lets you talk to the **embedded** agent runtime directly (no chat send unless you opt in), while reusing the same session store and thinking/verbose persistence as inbound auto-replies.
`clawdbot agent` lets you talk to the **embedded** agent runtime directly (no chat send unless you opt in), while reusing the same session store and thinking/verbose persistence as inbound auto-replies.
## Behavior
- Required: `--message <text>`
docs/agent.md
+13 -13
View File
@@ -6,13 +6,13 @@ read_when:
<!-- {% raw %} -->
# Agent Runtime 🤖
CLAWDIS runs a single embedded agent runtime derived from **p-mono** (internal name: **p**).
CLAWDBOT runs a single embedded agent runtime derived from **p-mono** (internal name: **p**).
## Workspace (required)
You must set an agent home directory via `agent.workspace`. CLAWDIS uses this as the agent’s **only** working directory (`cwd`) for tools and context.
You must set an agent home directory via `agent.workspace`. CLAWDBOT uses this as the agent’s **only** working directory (`cwd`) for tools and context.
Recommended: use `clawdis setup` to create `~/.clawdis/clawdis.json` if missing and initialize the workspace files.
Recommended: use `clawdbot setup` to create `~/.clawdbot/clawdbot.json` if missing and initialize the workspace files.
If `agent.sandbox` is enabled, non-main sessions can override this with
per-session workspaces under `agent.sandbox.workspaceRoot` (see
@@ -20,7 +20,7 @@ per-session workspaces under `agent.sandbox.workspaceRoot` (see
## Bootstrap files (injected)
Inside `agent.workspace`, CLAWDIS expects these user-editable files:
Inside `agent.workspace`, CLAWDBOT expects these user-editable files:
- `AGENTS.md` — operating instructions + “memory”
- `SOUL.md` — persona, boundaries, tone
- `TOOLS.md` — user-maintained tool notes (e.g. `imsg`, `sag`, conventions)
@@ -28,9 +28,9 @@ Inside `agent.workspace`, CLAWDIS expects these user-editable files:
- `IDENTITY.md` — agent name/vibe/emoji
- `USER.md` — user profile + preferred address
On the first turn of a new session, CLAWDIS injects the contents of these files directly into the agent context.
On the first turn of a new session, CLAWDBOT injects the contents of these files directly into the agent context.
If a file is missing, CLAWDIS injects a single “missing file” marker line (and `clawdis setup` will create a safe default template).
If a file is missing, CLAWDBOT injects a single “missing file” marker line (and `clawdbot setup` will create a safe default template).
## Built-in tools (internal)
@@ -38,16 +38,16 @@ p’s embedded core tools (read/bash/edit/write and related internals) are defin
## Skills
Clawdis loads skills from three locations (workspace wins on name conflict):
Clawdbot loads skills from three locations (workspace wins on name conflict):
- Bundled (shipped with the install)
- Managed/local: `~/.clawdis/skills`
- Managed/local: `~/.clawdbot/skills`
- Workspace: `<workspace>/skills`
Skills can be gated by config/env (see `skills` in `docs/configuration.md`).
## p-mono integration
Clawdis reuses pieces of the p-mono codebase (models/tools), but **session management, discovery, and tool wiring are Clawdis-owned**.
Clawdbot reuses pieces of the p-mono codebase (models/tools), but **session management, discovery, and tool wiring are Clawdbot-owned**.
- No p-coding agent runtime.
- No `~/.pi/agent` or `<workspace>/.pi` settings are consulted.
@@ -61,15 +61,15 @@ Apply these notes **only** when the user is Peter Steinberger at steipete.
- Peter travels between **Vienna** and **London**; there are two networks bridged via **Tailscale**.
- For debugging, connect to the Mac Studio (London) or MacBook Pro (primary).
- There is also an **M1 MacBook Pro** on the Vienna tailnet you can use to access the Vienna network.
- Nodes can be accessed via the `clawdis` binary (`pnpm clawdis` in `~/Projects/clawdis`).
- See also `skills/clawdis*` for node/browser/canvas/cron usage.
- Nodes can be accessed via the `clawdbot` binary (`pnpm clawdbot` in `~/Projects/clawdbot`).
- See also `skills/clawdbot*` for node/browser/canvas/cron usage.
## Sessions
Session transcripts are stored as JSONL at:
- `~/.clawdis/sessions/<SessionId>.jsonl`
- `~/.clawdbot/sessions/<SessionId>.jsonl`
The session ID is stable and chosen by CLAWDIS.
The session ID is stable and chosen by CLAWDBOT.
Legacy Pi/Tau session folders are **not** read.
## Steering while streaming
docs/android/connect.md
+15 -15
View File
@@ -1,5 +1,5 @@
---
summary: "Runbook: connect/pair the Android node to a Clawdis Gateway and use Canvas/Chat/Camera"
summary: "Runbook: connect/pair the Android node to a Clawdbot Gateway and use Canvas/Chat/Camera"
read_when:
- Pairing or reconnecting the Android node
- Debugging Android bridge discovery or auth
@@ -19,14 +19,14 @@ The Gateway WebSocket stays loopback-only (`ws://127.0.0.1:18789`). Android talk
- Same LAN with mDNS/NSD, **or**
- Same Tailscale tailnet using Wide-Area Bonjour / unicast DNS-SD (see below), **or**
- Manual bridge host/port (fallback)
- You can run the CLI (`clawdis`) on the gateway machine (or via SSH).
- You can run the CLI (`clawdbot`) on the gateway machine (or via SSH).
## 1) Start the Gateway (with bridge enabled)
Bridge is enabled by default (disable via `CLAWDIS_BRIDGE_ENABLED=0`).
Bridge is enabled by default (disable via `CLAWDBOT_BRIDGE_ENABLED=0`).
```bash
pnpm clawdis gateway --port 18789 --verbose
pnpm clawdbot gateway --port 18789 --verbose
```
Confirm in logs you see something like:
@@ -34,7 +34,7 @@ Confirm in logs you see something like:
For tailnet-only setups (recommended for Vienna ⇄ London), bind the bridge to the gateway machine’s Tailscale IP instead:
- Set `bridge.bind: "tailnet"` in `~/.clawdis/clawdis.json` on the gateway host.
- Set `bridge.bind: "tailnet"` in `~/.clawdbot/clawdbot.json` on the gateway host.
- Restart the Gateway / macOS menubar app.
## 2) Verify discovery (optional)
@@ -42,7 +42,7 @@ For tailnet-only setups (recommended for Vienna ⇄ London), bind the bridge to
From the gateway machine:
```bash
dns-sd -B _clawdis-bridge._tcp local.
dns-sd -B _clawdbot-bridge._tcp local.
```
More debugging notes: `docs/bonjour.md`.
@@ -51,8 +51,8 @@ More debugging notes: `docs/bonjour.md`.
Android NSD/mDNS discovery won’t cross networks. If your Android node and the gateway are on different networks but connected via Tailscale, use Wide-Area Bonjour / unicast DNS-SD instead:
1) Set up a DNS-SD zone (example `clawdis.internal.`) on the gateway host and publish `_clawdis-bridge._tcp` records.
2) Configure Tailscale split DNS for `clawdis.internal` pointing at that DNS server.
1) Set up a DNS-SD zone (example `clawdbot.internal.`) on the gateway host and publish `_clawdbot-bridge._tcp` records.
2) Configure Tailscale split DNS for `clawdbot.internal` pointing at that DNS server.
Details and example CoreDNS config: `docs/bonjour.md`.
@@ -74,8 +74,8 @@ After the first successful pairing, Android auto-reconnects on launch:
On the gateway machine:
```bash
clawdis nodes pending
clawdis nodes approve <requestId>
clawdbot nodes pending
clawdbot nodes approve <requestId>
```
Pairing details: `docs/gateway/pairing.md`.
@@ -84,11 +84,11 @@ Pairing details: `docs/gateway/pairing.md`.
- Via nodes status:
```bash
clawdis nodes status
clawdbot nodes status
```
- Via Gateway:
```bash
clawdis gateway call node.list --params "{}"
clawdbot gateway call node.list --params "{}"
```
## 6) Chat + history
@@ -112,13 +112,13 @@ Note: nodes always use the standalone canvas host on `canvasHost.port` (default
2) Navigate the node to it (LAN):
```bash
clawdis nodes invoke --node "<Android Node>" --command canvas.navigate --params '{"url":"http://<gateway-hostname>.local:18793/__clawdis__/canvas/"}'
clawdbot nodes invoke --node "<Android Node>" --command canvas.navigate --params '{"url":"http://<gateway-hostname>.local:18793/__clawdbot__/canvas/"}'
```
Tailnet (optional): if both devices are on Tailscale, use a MagicDNS name or tailnet IP instead of `.local`, e.g. `http://<gateway-magicdns>:18793/__clawdis__/canvas/`.
Tailnet (optional): if both devices are on Tailscale, use a MagicDNS name or tailnet IP instead of `.local`, e.g. `http://<gateway-magicdns>:18793/__clawdbot__/canvas/`.
This server injects a live-reload client into HTML and reloads on file changes.
The A2UI host lives at `http://<gateway-host>:18793/__clawdis__/a2ui/`.
The A2UI host lives at `http://<gateway-host>:18793/__clawdbot__/a2ui/`.
Canvas commands (foreground only):
- `canvas.eval`, `canvas.snapshot`, `canvas.navigate` (use `{"url":""}` or `{"url":"/"}` to return to the default scaffold). `canvas.snapshot` returns `{ format, base64 }` (default `format="jpeg"`).
docs/architecture.md
+4 -4
View File
@@ -11,7 +11,7 @@ Last updated: 2025-12-09
- A single long-lived **Gateway** process owns all messaging surfaces (WhatsApp via Baileys, Telegram via grammY, Discord via discord.js) and the control/event plane.
- All clients (macOS app, CLI, web UI, automations) connect to the Gateway over one transport: **WebSocket on 127.0.0.1:18789** (tunnel or VPN for remote).
- One Gateway per host; it is the only place that is allowed to open a WhatsApp session. All sends/agent runs go through it.
- By default: the Gateway exposes a Canvas host on `canvasHost.port` (default `18793`), serving `~/clawd/canvas` at `/__clawdis__/canvas/` with live-reload; disable via `canvasHost.enabled=false` or `CLAWDIS_SKIP_CANVAS_HOST=1`.
- By default: the Gateway exposes a Canvas host on `canvasHost.port` (default `18793`), serving `~/clawd/canvas` at `/__clawdbot__/canvas/` with live-reload; disable via `canvasHost.enabled=false` or `CLAWDBOT_SKIP_CANVAS_HOST=1`.
## Components and flows
- **Gateway (daemon)**
@@ -21,7 +21,7 @@ Last updated: 2025-12-09
- **Clients (mac app / CLI / web admin)**
- One WS connection per client.
- Send requests (`health`, `status`, `send`, `agent`, `system-presence`, toggles) and subscribe to events (`tick`, `agent`, `presence`, `shutdown`).
- On macOS, the app can also be invoked via deep links (`clawdis://agent?...`) which translate into the same Gateway `agent` request path (see `docs/clawdis-mac.md`).
- On macOS, the app can also be invoked via deep links (`clawdbot://agent?...`) which translate into the same Gateway `agent` request path (see `docs/clawdbot-mac.md`).
- **Agent process (Pi)**
- Spawned by the Gateway on demand for `agent` calls; streams events back over the same WS connection.
- **WebChat**
@@ -53,7 +53,7 @@ Client Gateway
- After handshake:
- Requests: `{type:"req", id, method, params}` → `{type:"res", id, ok, payload|error}`
- Events: `{type:"event", event:"agent"|"presence"|"tick"|"shutdown", payload, seq?, stateVersion?}`
- If `CLAWDIS_GATEWAY_TOKEN` (or `--token`) is set, `connect.params.auth.token` must match; otherwise the socket closes with policy violation.
- If `CLAWDBOT_GATEWAY_TOKEN` (or `--token`) is set, `connect.params.auth.token` must match; otherwise the socket closes with policy violation.
- Presence payload is structured, not free text: `{host, ip, version, mode, lastInputSeconds?, ts, reason?, tags?[], instanceId? }`.
- Agent runs are acked `{runId,status:"accepted"}` then complete with a final res `{runId,status,summary}`; streamed output arrives as `event:"agent"`.
- Protocol versions are bumped on breaking changes; clients must match `minClient`; Gateway chooses within client’s min/max.
@@ -80,7 +80,7 @@ Client Gateway
- Same protocol over the tunnel; same handshake. If a shared token is configured, clients must send it in `connect.params.auth.token` even over the tunnel.
## Operations snapshot
- Start: `clawdis gateway` (foreground, logs to stdout).
- Start: `clawdbot gateway` (foreground, logs to stdout).
Supervise with launchd/systemd for restarts.
- Health: request `health` over WS; also surfaced in `hello-ok.health`.
- Metrics/logging: keep outside this spec; gateway should expose Prometheus text or structured logs separately.
docs/assets/theme.js
+1 -1
View File
@@ -1,4 +1,4 @@
const THEME_STORAGE_KEY = "clawdis:theme";
const THEME_STORAGE_KEY = "clawdbot:theme";
function safeGet(key) {
try {
docs/audio.md
+1 -1
View File
@@ -7,7 +7,7 @@ read_when:
# Audio / Voice Notes — 2025-12-05
## What works
- **Optional transcription**: If `routing.transcribeAudio.command` is set in `~/.clawdis/clawdis.json`, CLAWDIS will:
- **Optional transcription**: If `routing.transcribeAudio.command` is set in `~/.clawdbot/clawdbot.json`, CLAWDBOT will:
1) Download inbound audio to a temp path when WhatsApp only provides a URL.
2) Run the configured CLI (templated with `{{MediaPath}}`), expecting transcript on stdout.
3) Replace `Body` with the transcript, set `{{Transcript}}`, and prepend the original media path plus a `Transcript:` section in the command prompt so models see both.
docs/background-process.md
+1 -1
View File
@@ -7,7 +7,7 @@ read_when:
# Background Bash + Process Tool
Clawdis runs shell commands through the `bash` tool and keeps long‑running tasks in memory. The `process` tool manages those background sessions.
Clawdbot runs shell commands through the `bash` tool and keeps long‑running tasks in memory. The `process` tool manages those background sessions.
## bash tool
docs/bonjour.md
+27 -27
View File
@@ -6,7 +6,7 @@ read_when:
---
# Bonjour / mDNS discovery
Clawdis uses Bonjour (mDNS / DNS-SD) as a **LAN-only convenience** to discover a running Gateway bridge transport. It is best-effort and does **not** replace SSH or Tailnet-based connectivity.
Clawdbot uses Bonjour (mDNS / DNS-SD) as a **LAN-only convenience** to discover a running Gateway bridge transport. It is best-effort and does **not** replace SSH or Tailnet-based connectivity.
## Wide-Area Bonjour (Unicast DNS-SD) over Tailscale
@@ -15,19 +15,19 @@ If you want iOS node auto-discovery while the Gateway is on another network (e.g
High level:
1) Run a DNS server on the gateway host (reachable via tailnet IP).
2) Publish DNS-SD records for `_clawdis-bridge._tcp` in a dedicated zone (example: `clawdis.internal.`).
3) Configure Tailscale **split DNS** so `clawdis.internal` resolves via that DNS server for clients (including iOS).
2) Publish DNS-SD records for `_clawdbot-bridge._tcp` in a dedicated zone (example: `clawdbot.internal.`).
3) Configure Tailscale **split DNS** so `clawdbot.internal` resolves via that DNS server for clients (including iOS).
Clawdis standardizes on the discovery domain `clawdis.internal.` for this mode. iOS/Android nodes browse both `local.` and `clawdis.internal.` automatically (no per-device knob).
Clawdbot standardizes on the discovery domain `clawdbot.internal.` for this mode. iOS/Android nodes browse both `local.` and `clawdbot.internal.` automatically (no per-device knob).
### Gateway config (recommended)
On the gateway host (the machine running the Gateway bridge), add to `~/.clawdis/clawdis.json` (JSON5):
On the gateway host (the machine running the Gateway bridge), add to `~/.clawdbot/clawdbot.json` (JSON5):
```json5
{
bridge: { bind: "tailnet" }, // tailnet-only (recommended)
discovery: { wideArea: { enabled: true } } // enables clawdis.internal DNS-SD publishing
discovery: { wideArea: { enabled: true } } // enables clawdbot.internal DNS-SD publishing
}
```
@@ -36,20 +36,20 @@ On the gateway host (the machine running the Gateway bridge), add to `~/.clawdis
On the gateway host (macOS), run:
```bash
clawdis dns setup --apply
clawdbot dns setup --apply
```
This installs CoreDNS and configures it to:
- listen on port 53 **only** on the gateway’s Tailscale interface IPs
- serve the zone `clawdis.internal.` from the gateway-owned zone file `~/.clawdis/dns/clawdis.internal.db`
- serve the zone `clawdbot.internal.` from the gateway-owned zone file `~/.clawdbot/dns/clawdbot.internal.db`
The Gateway writes/updates that zone file when `discovery.wideArea.enabled` is true.
Validate from any tailnet-connected machine:
```bash
dns-sd -B _clawdis-bridge._tcp clawdis.internal.
dig @<TAILNET_IPV4> -p 53 _clawdis-bridge._tcp.clawdis.internal PTR +short
dns-sd -B _clawdbot-bridge._tcp clawdbot.internal.
dig @<TAILNET_IPV4> -p 53 _clawdbot-bridge._tcp.clawdbot.internal PTR +short
```
### Tailscale DNS settings
@@ -57,9 +57,9 @@ dig @<TAILNET_IPV4> -p 53 _clawdis-bridge._tcp.clawdis.internal PTR +short
In the Tailscale admin console:
- Add a nameserver pointing at the gateway’s tailnet IP (UDP/TCP 53).
- Add split DNS so the domain `clawdis.internal` uses that nameserver.
- Add split DNS so the domain `clawdbot.internal` uses that nameserver.
Once clients accept tailnet DNS, iOS nodes can browse `_clawdis-bridge._tcp` in `clawdis.internal.` without multicast.
Once clients accept tailnet DNS, iOS nodes can browse `_clawdbot-bridge._tcp` in `clawdbot.internal.` without multicast.
Wide-area beacons also include `tailnetDns` (when available) so the macOS app can auto-fill SSH targets off-LAN.
### Bridge listener security (recommended)
@@ -68,21 +68,21 @@ The bridge port (default `18790`) is a plain TCP service. By default it binds to
For a tailnet-only setup, bind it to the Tailscale IP instead:
- Set `bridge.bind: "tailnet"` in `~/.clawdis/clawdis.json`.
- Set `bridge.bind: "tailnet"` in `~/.clawdbot/clawdbot.json`.
- Restart the Gateway (or restart the macOS menubar app via `./scripts/restart-mac.sh` on that machine).
This keeps the bridge reachable only from devices on your tailnet (while still listening on loopback for local/SSH port-forwards).
## What advertises
Only the **Node Gateway** (`clawd` / `clawdis gateway`) advertises Bonjour beacons.
Only the **Node Gateway** (`clawd` / `clawdbot gateway`) advertises Bonjour beacons.
- Implementation: `src/infra/bonjour.ts`
- Gateway wiring: `src/gateway/server.ts`
## Service types
- `_clawdis-bridge._tcp` — bridge transport beacon (used by macOS/iOS/Android nodes).
- `_clawdbot-bridge._tcp` — bridge transport beacon (used by macOS/iOS/Android nodes).
## TXT keys (non-secret hints)
@@ -93,8 +93,8 @@ The Gateway advertises small non-secret hints to make UI flows convenient:
- `sshPort=<port>` (defaults to 22 when not overridden)
- `gatewayPort=<port>` (informational; the Gateway WS is typically loopback-only)
- `bridgePort=<port>` (only when bridge is enabled)
- `canvasPort=<port>` (only when the canvas host is enabled + reachable; default `18793`; serves `/__clawdis__/canvas/`)
- `cliPath=<path>` (optional; absolute path to a runnable `clawdis` entrypoint or binary)
- `canvasPort=<port>` (only when the canvas host is enabled + reachable; default `18793`; serves `/__clawdbot__/canvas/`)
- `cliPath=<path>` (optional; absolute path to a runnable `clawdbot` entrypoint or binary)
- `tailnetDns=<magicdns>` (optional hint; auto-detected from Tailscale when available; may be absent)
## Debugging on macOS
@@ -102,9 +102,9 @@ The Gateway advertises small non-secret hints to make UI flows convenient:
Useful built-in tools:
- Browse instances:
- `dns-sd -B _clawdis-bridge._tcp local.`
- `dns-sd -B _clawdbot-bridge._tcp local.`
- Resolve one instance (replace `<instance>`):
- `dns-sd -L "<instance>" _clawdis-bridge._tcp local.`
- `dns-sd -L "<instance>" _clawdbot-bridge._tcp local.`
If browsing shows instances but resolving fails, you’re usually hitting a LAN policy / multicast issue.
@@ -120,7 +120,7 @@ Look for `bonjour:` lines, especially:
## Debugging on iOS node
The iOS node app discovers bridges via `NWBrowser` browsing `_clawdis-bridge._tcp`.
The iOS node app discovers bridges via `NWBrowser` browsing `_clawdbot-bridge._tcp`.
To capture what the browser is doing:
@@ -142,16 +142,16 @@ The log includes browser state transitions (`ready`, `waiting`, `failed`, `cance
Bonjour/DNS-SD often escapes bytes in service instance names as decimal `\\DDD` sequences (e.g. spaces become `\\032`).
- This is normal at the protocol level.
- UIs should decode for display (iOS uses `BonjourEscapes.decode` in `apps/shared/ClawdisKit`).
- UIs should decode for display (iOS uses `BonjourEscapes.decode` in `apps/shared/ClawdbotKit`).
## Disabling / configuration
- `CLAWDIS_DISABLE_BONJOUR=1` disables advertising.
- `CLAWDIS_BRIDGE_ENABLED=0` disables the bridge listener (and therefore the bridge beacon).
- `bridge.bind` / `bridge.port` in `~/.clawdis/clawdis.json` control bridge bind/port (preferred).
- `CLAWDIS_BRIDGE_HOST` / `CLAWDIS_BRIDGE_PORT` still work as a back-compat override when `bridge.bind` / `bridge.port` are not set.
- `CLAWDIS_SSH_PORT` overrides the SSH port advertised in `_clawdis-bridge._tcp`.
- `CLAWDIS_TAILNET_DNS` publishes a `tailnetDns` hint (MagicDNS) in `_clawdis-bridge._tcp`. If unset, the gateway auto-detects Tailscale and publishes the MagicDNS name when possible.
- `CLAWDBOT_DISABLE_BONJOUR=1` disables advertising.
- `CLAWDBOT_BRIDGE_ENABLED=0` disables the bridge listener (and therefore the bridge beacon).
- `bridge.bind` / `bridge.port` in `~/.clawdbot/clawdbot.json` control bridge bind/port (preferred).
- `CLAWDBOT_BRIDGE_HOST` / `CLAWDBOT_BRIDGE_PORT` still work as a back-compat override when `bridge.bind` / `bridge.port` are not set.
- `CLAWDBOT_SSH_PORT` overrides the SSH port advertised in `_clawdbot-bridge._tcp`.
- `CLAWDBOT_TAILNET_DNS` publishes a `tailnetDns` hint (MagicDNS) in `_clawdbot-bridge._tcp`. If unset, the gateway auto-detects Tailscale and publishes the MagicDNS name when possible.
## Related docs
docs/browser.md
+43 -43
View File
@@ -26,7 +26,7 @@ Add a dedicated settings section (preferably under **Skills** or its own "Browse
- When off: no browser is launched, and browser tools return "disabled".
- **Browser control URL** (`default: http://127.0.0.1:18791`)
- Interpreted as the base URL of the local/remote browser-control server.
- If the URL host is not loopback, Clawdis must **not** attempt to launch a local
- If the URL host is not loopback, Clawdbot must **not** attempt to launch a local
browser; it only connects.
- **CDP URL** (`default: controlUrl + 1`)
- Base URL for Chrome DevTools Protocol (e.g. `http://127.0.0.1:18792`).
@@ -37,7 +37,7 @@ Add a dedicated settings section (preferably under **Skills** or its own "Browse
avoid accidentally launching a local browser.
- **Accent color** (`default: #FF4500`, "lobster-orange")
- Used to theme the clawd browser profile (best-effort) and to tint UI indicators
in Clawdis.
in Clawdbot.
Optional (advanced, can be hidden behind Debug initially):
- **Use headless browser** (`default: off`)
@@ -48,14 +48,14 @@ Optional (advanced, can be hidden behind Debug initially):
### Port convention
Clawdis already uses:
Clawdbot already uses:
- Gateway WebSocket: `18789`
- Bridge (voice/node): `18790`
For the clawd browser-control server, use "family" ports:
- Browser control HTTP API: `18791` (bridge + 1)
- Browser CDP/debugging port: `18792` (control + 1)
- Canvas host HTTP: `18793` by default, mounted at `/__clawdis__/canvas/`
- Canvas host HTTP: `18793` by default, mounted at `/__clawdbot__/canvas/`
The user usually only configures the **control URL** (port `18791`). CDP is an
internal detail.
@@ -65,8 +65,8 @@ internal detail.
1) **Dedicated user data dir**
- Never attach to or reuse the user's default Chrome profile.
- Store clawd browser state under an app-owned directory, e.g.:
- `~/Library/Application Support/Clawdis/browser/clawd/` (mac app)
- or `~/.clawdis/browser/clawd/` (gateway/CLI)
- `~/Library/Application Support/Clawdbot/browser/clawd/` (mac app)
- or `~/.clawdbot/browser/clawd/` (gateway/CLI)
2) **Dedicated ports**
- Never use `9222` (reserved for ad-hoc dev workflows; avoids colliding with
@@ -79,7 +79,7 @@ internal detail.
## Browser selection (macOS + Linux)
On startup (when enabled + local URL), Clawdis chooses the browser executable
On startup (when enabled + local URL), Clawdbot chooses the browser executable
in this order:
1) **Google Chrome Canary** (if installed)
2) **Chromium** (if installed)
@@ -150,14 +150,14 @@ Hooks (arming):
"Closed" means:
- control server not reachable, or server reports no browser.
Clawdis should treat "open/closed" as a health check (fast path), not by scanning
Clawdbot should treat "open/closed" as a health check (fast path), not by scanning
global Chrome processes (avoid false positives).
## Multi-profile support
Clawdis supports multiple named browser profiles, each with:
Clawdbot supports multiple named browser profiles, each with:
- Dedicated CDP port (auto-allocated from 18800-18899) **or** a per-profile CDP URL
- Persistent user data directory (`~/.clawdis/browser/<name>/user-data/`)
- Persistent user data directory (`~/.clawdbot/browser/<name>/user-data/`)
- Unique color for visual distinction
### Configuration
@@ -224,44 +224,44 @@ The agent should not assume tabs are ephemeral. It should:
All commands accept `--profile <name>` to target a specific profile (default: `clawd`).
Profile management:
- `clawdis browser profiles`
- `clawdis browser create-profile --name work`
- `clawdis browser create-profile --name remote --cdp-url http://10.0.0.42:9222`
- `clawdis browser delete-profile --name work`
- `clawdbot browser profiles`
- `clawdbot browser create-profile --name work`
- `clawdbot browser create-profile --name remote --cdp-url http://10.0.0.42:9222`
- `clawdbot browser delete-profile --name work`
Basics:
- `clawdis browser status`
- `clawdis browser start`
- `clawdis browser stop`
- `clawdis browser reset-profile`
- `clawdis browser tabs`
- `clawdis browser open https://example.com`
- `clawdis browser focus abcd1234`
- `clawdis browser close abcd1234`
- `clawdbot browser status`
- `clawdbot browser start`
- `clawdbot browser stop`
- `clawdbot browser reset-profile`
- `clawdbot browser tabs`
- `clawdbot browser open https://example.com`
- `clawdbot browser focus abcd1234`
- `clawdbot browser close abcd1234`
Inspection:
- `clawdis browser screenshot`
- `clawdis browser screenshot --full-page`
- `clawdis browser screenshot --ref 12`
- `clawdis browser snapshot`
- `clawdis browser snapshot --format aria --limit 200`
- `clawdbot browser screenshot`
- `clawdbot browser screenshot --full-page`
- `clawdbot browser screenshot --ref 12`
- `clawdbot browser snapshot`
- `clawdbot browser snapshot --format aria --limit 200`
Actions:
- `clawdis browser navigate https://example.com`
- `clawdis browser resize 1280 720`
- `clawdis browser click 12 --double`
- `clawdis browser type 23 "hello" --submit`
- `clawdis browser press Enter`
- `clawdis browser hover 44`
- `clawdis browser drag 10 11`
- `clawdis browser select 9 OptionA OptionB`
- `clawdis browser upload /tmp/file.pdf`
- `clawdis browser fill --fields '[{\"ref\":\"1\",\"value\":\"Ada\"}]'`
- `clawdis browser dialog --accept`
- `clawdis browser wait --text "Done"`
- `clawdis browser evaluate --fn '(el) => el.textContent' --ref 7`
- `clawdis browser evaluate --fn "document.querySelector('.my-class').click()"`
- `clawdis browser console --level error`
- `clawdis browser pdf`
- `clawdbot browser navigate https://example.com`
- `clawdbot browser resize 1280 720`
- `clawdbot browser click 12 --double`
- `clawdbot browser type 23 "hello" --submit`
- `clawdbot browser press Enter`
- `clawdbot browser hover 44`
- `clawdbot browser drag 10 11`
- `clawdbot browser select 9 OptionA OptionB`
- `clawdbot browser upload /tmp/file.pdf`
- `clawdbot browser fill --fields '[{\"ref\":\"1\",\"value\":\"Ada\"}]'`
- `clawdbot browser dialog --accept`
- `clawdbot browser wait --text "Done"`
- `clawdbot browser evaluate --fn '(el) => el.textContent' --ref 7`
- `clawdbot browser evaluate --fn "document.querySelector('.my-class').click()"`
- `clawdbot browser console --level error`
- `clawdbot browser pdf`
Notes:
- `upload` and `dialog` are **arming** calls; run them before the click/press that triggers the chooser/dialog.
docs/camera.md
+18 -18
View File
@@ -7,7 +7,7 @@ read_when:
# Camera capture (agent)
Clawdis supports **camera capture** for agent workflows:
Clawdbot supports **camera capture** for agent workflows:
- **iOS node** (paired via Gateway): capture a **photo** (`jpg`) or **short video clip** (`mp4`, with optional audio) via `node.invoke`.
- **Android node** (paired via Gateway): capture a **photo** (`jpg`) or **short video clip** (`mp4`, with optional audio) via `node.invoke`.
@@ -67,10 +67,10 @@ The easiest way to get attachments is via the CLI helper, which writes decoded m
Examples:
```bash
clawdis nodes camera snap --node <id> # default: both front + back (2 MEDIA lines)
clawdis nodes camera snap --node <id> --facing front
clawdis nodes camera clip --node <id> --duration 3000
clawdis nodes camera clip --node <id> --no-audio
clawdbot nodes camera snap --node <id> # default: both front + back (2 MEDIA lines)
clawdbot nodes camera snap --node <id> --facing front
clawdbot nodes camera clip --node <id> --duration 3000
clawdbot nodes camera clip --node <id> --no-audio
```
Notes:
@@ -108,30 +108,30 @@ Photos are recompressed to keep the base64 payload under 5 MB.
The macOS companion app exposes a checkbox:
- **Settings → General → Allow Camera** (`clawdis.cameraEnabled`)
- **Settings → General → Allow Camera** (`clawdbot.cameraEnabled`)
- Default: **off**
- When off: camera requests return “Camera disabled by user”.
### CLI helper (node invoke)
Use the main `clawdis` CLI to invoke camera commands on the macOS node.
Use the main `clawdbot` CLI to invoke camera commands on the macOS node.
Examples:
```bash
clawdis nodes camera list --node <id> # list camera ids
clawdis nodes camera snap --node <id> # prints MEDIA:<path>
clawdis nodes camera snap --node <id> --max-width 1280
clawdis nodes camera snap --node <id> --delay-ms 2000
clawdis nodes camera snap --node <id> --device-id <id>
clawdis nodes camera clip --node <id> --duration 10s # prints MEDIA:<path>
clawdis nodes camera clip --node <id> --duration-ms 3000 # prints MEDIA:<path> (legacy flag)
clawdis nodes camera clip --node <id> --device-id <id>
clawdis nodes camera clip --node <id> --no-audio
clawdbot nodes camera list --node <id> # list camera ids
clawdbot nodes camera snap --node <id> # prints MEDIA:<path>
clawdbot nodes camera snap --node <id> --max-width 1280
clawdbot nodes camera snap --node <id> --delay-ms 2000
clawdbot nodes camera snap --node <id> --device-id <id>
clawdbot nodes camera clip --node <id> --duration 10s # prints MEDIA:<path>
clawdbot nodes camera clip --node <id> --duration-ms 3000 # prints MEDIA:<path> (legacy flag)
clawdbot nodes camera clip --node <id> --device-id <id>
clawdbot nodes camera clip --node <id> --no-audio
```
Notes:
- `clawdis nodes camera snap` defaults to `maxWidth=1600` unless overridden.
- `clawdbot nodes camera snap` defaults to `maxWidth=1600` unless overridden.
- On macOS, `camera.snap` waits `delayMs` (default 2000ms) after warm-up/exposure settle before capturing.
- Photo payloads are recompressed to keep base64 under 5 MB.
@@ -145,7 +145,7 @@ Notes:
For *screen* video (not camera), use the macOS companion:
```bash
clawdis nodes screen record --node <id> --duration 10s --fps 15 # prints MEDIA:<path>
clawdbot nodes screen record --node <id> --duration 10s --fps 15 # prints MEDIA:<path>
```
Notes:
docs/clawd.md
+22 -22
View File
@@ -1,13 +1,13 @@
---
summary: "End-to-end guide for running Clawdis as a personal assistant with safety cautions"
summary: "End-to-end guide for running Clawdbot as a personal assistant with safety cautions"
read_when:
- Onboarding a new assistant instance
- Reviewing safety/permission implications
---
<!-- {% raw %} -->
# Building a personal assistant with CLAWDIS (Clawd-style)
# Building a personal assistant with CLAWDBOT (Clawd-style)
CLAWDIS is a WhatsApp + Telegram + Discord gateway for **Pi** agents. This guide is the “personal assistant” setup: one dedicated WhatsApp number that behaves like your always-on agent.
CLAWDBOT is a WhatsApp + Telegram + Discord gateway for **Pi** agents. This guide is the “personal assistant” setup: one dedicated WhatsApp number that behaves like your always-on agent.
## ⚠️ Safety first
@@ -24,7 +24,7 @@ Start conservative:
## Prerequisites
- Node **22+**
- CLAWDIS available on PATH (recommended during development: from source + global link)
- CLAWDBOT available on PATH (recommended during development: from source + global link)
- A second phone number (SIM/eSIM/prepaid) for the assistant
From source (recommended while the npm package is still settling):
@@ -49,28 +49,28 @@ Your Phone (personal) Second Phone (assistant)
▼
┌─────────────────┐
│ Your Mac │
│ (clawdis) │
│ (clawdbot) │
│ Pi agent │
└─────────────────┘
```
If you link your personal WhatsApp to CLAWDIS, every message to you becomes “agent input”. That’s rarely what you want.
If you link your personal WhatsApp to CLAWDBOT, every message to you becomes “agent input”. That’s rarely what you want.
## 5-minute quick start
1) Pair WhatsApp Web (shows QR; scan with the assistant phone):
```bash
clawdis login
clawdbot login
```
2) Start the Gateway (leave it running):
```bash
clawdis gateway --port 18789
clawdbot gateway --port 18789
```
3) Put a minimal config in `~/.clawdis/clawdis.json`:
3) Put a minimal config in `~/.clawdbot/clawdbot.json`:
```json5
{
@@ -86,12 +86,12 @@ Now message the assistant number from your allowlisted phone.
Clawd reads operating instructions and “memory” from its workspace directory.
By default, Clawdis uses `~/clawd` as the agent workspace, and will create it (plus starter `AGENTS.md`, `SOUL.md`, `TOOLS.md`) automatically on setup/first agent run.
By default, Clawdbot uses `~/clawd` as the agent workspace, and will create it (plus starter `AGENTS.md`, `SOUL.md`, `TOOLS.md`) automatically on setup/first agent run.
Tip: treat this folder like Clawd’s “memory” and make it a git repo (ideally private) so your `AGENTS.md` + memory files are backed up.
```bash
clawdis setup
clawdbot setup
```
Optional: choose a different workspace with `agent.workspace` (supports `~`).
@@ -106,7 +106,7 @@ Optional: choose a different workspace with `agent.workspace` (supports `~`).
## The config that turns it into “an assistant”
CLAWDIS defaults to a good assistant setup, but you’ll usually want to tune:
CLAWDBOT defaults to a good assistant setup, but you’ll usually want to tune:
- persona/instructions in `SOUL.md`
- thinking defaults (if desired)
- heartbeats (once you trust it)
@@ -145,15 +145,15 @@ Example:
## Sessions and memory
- Session files: `~/.clawdis/sessions/{{SessionId}}.jsonl`
- Session metadata (token usage, last route, etc): `~/.clawdis/sessions/sessions.json` (legacy: `~/.clawdis/sessions.json`)
- Session files: `~/.clawdbot/sessions/{{SessionId}}.jsonl`
- Session metadata (token usage, last route, etc): `~/.clawdbot/sessions/sessions.json` (legacy: `~/.clawdbot/sessions.json`)
- `/new` or `/reset` starts a fresh session for that chat (configurable via `resetTriggers`). If sent alone, the agent replies with a short hello to confirm the reset.
## Heartbeats (proactive mode)
When `agent.heartbeat.every` is set to a positive interval, CLAWDIS periodically runs a heartbeat prompt (default: `HEARTBEAT`).
When `agent.heartbeat.every` is set to a positive interval, CLAWDBOT periodically runs a heartbeat prompt (default: `HEARTBEAT`).
- If the agent replies with `HEARTBEAT_OK` (exact token), CLAWDIS suppresses outbound delivery for that heartbeat.
- If the agent replies with `HEARTBEAT_OK` (exact token), CLAWDBOT suppresses outbound delivery for that heartbeat.
```json5
{
@@ -177,23 +177,23 @@ Here’s the screenshot.
MEDIA:/tmp/screenshot.png
```
CLAWDIS extracts these and sends them as media alongside the text.
CLAWDBOT extracts these and sends them as media alongside the text.
## Operations checklist
```bash
clawdis status # local status (creds, sessions, queued events)
clawdis status --deep # also probes the running Gateway (WA connect + Telegram)
clawdis health --json # gateway health snapshot (WS)
clawdbot status # local status (creds, sessions, queued events)
clawdbot status --deep # also probes the running Gateway (WA connect + Telegram)
clawdbot health --json # gateway health snapshot (WS)
```
Logs live under `/tmp/clawdis/` (default: `clawdis-YYYY-MM-DD.log`).
Logs live under `/tmp/clawdbot/` (default: `clawdbot-YYYY-MM-DD.log`).
## Next steps
- WebChat: [WebChat](./webchat.md)
- Gateway ops: [Gateway runbook](./gateway.md)
- Cron + wakeups: [Cron + wakeups](./cron.md)
- macOS menu bar companion: [Clawdis macOS app](./clawdis-mac.md)
- macOS menu bar companion: [Clawdbot macOS app](./clawdbot-mac.md)
- Security: [Security](./security.md)
<!-- {% endraw %} -->
docs/clawdis-mac.md → docs/clawdbot-mac.md
+25 -25
View File
@@ -1,37 +1,37 @@
---
summary: "Spec for the Clawdis macOS companion menu bar app (gateway + node broker)"
summary: "Spec for the Clawdbot macOS companion menu bar app (gateway + node broker)"
read_when:
- Implementing macOS app features
- Changing gateway lifecycle or node bridging on macOS
---
# Clawdis macOS Companion (menu bar + gateway broker)
# Clawdbot macOS Companion (menu bar + gateway broker)
Author: steipete · Status: draft spec · Date: 2025-12-20
## Purpose
- Single macOS menu-bar app named **Clawdis** that:
- Shows native notifications for Clawdis/clawdis events.
- Single macOS menu-bar app named **Clawdbot** that:
- Shows native notifications for Clawdbot/clawdbot events.
- Owns TCC prompts (Notifications, Accessibility, Screen Recording, Automation/AppleScript, Microphone, Speech Recognition).
- Runs (or connects to) the **Gateway** and exposes itself as a **node** so agents can reach macOS‑only features.
- Hosts **PeekabooBridge** for UI automation (consumed by `peekaboo`; see `docs/mac/peekaboo.md`).
- Installs a single CLI (`clawdis`) by symlinking the bundled binary.
- Installs a single CLI (`clawdbot`) by symlinking the bundled binary.
## High-level design
- SwiftPM package in `apps/macos/` (macOS 15+, Swift 6).
- Targets:
- `ClawdisIPC` (shared Codable types + helpers for app‑internal actions).
- `Clawdis` (LSUIElement MenuBarExtra app; hosts Gateway + node bridge + PeekabooBridgeHost).
- Bundle ID: `com.clawdis.mac`.
- `ClawdbotIPC` (shared Codable types + helpers for app‑internal actions).
- `Clawdbot` (LSUIElement MenuBarExtra app; hosts Gateway + node bridge + PeekabooBridgeHost).
- Bundle ID: `com.clawdbot.mac`.
- Bundled runtime binaries live under `Contents/Resources/Relay/`:
- `clawdis` (bun‑compiled relay: CLI + gateway-daemon)
- The app symlinks `clawdis` into `/usr/local/bin` and `/opt/homebrew/bin`.
- `clawdbot` (bun‑compiled relay: CLI + gateway-daemon)
- The app symlinks `clawdbot` into `/usr/local/bin` and `/opt/homebrew/bin`.
## Gateway + node bridge
- The mac app runs the Gateway in **local** mode (unless configured remote).
- The gateway port is configurable via `gateway.port` or `CLAWDIS_GATEWAY_PORT` (default 18789). The mac app reads that value for launchd, probes, and remote SSH tunnels.
- The gateway port is configurable via `gateway.port` or `CLAWDBOT_GATEWAY_PORT` (default 18789). The mac app reads that value for launchd, probes, and remote SSH tunnels.
- The mac app connects to the bridge as a **node** and advertises capabilities/commands.
- Agent‑facing actions are exposed via `node.invoke` (no local control socket).
- The mac app watches `~/.clawdis/clawdis.json` and switches modes live when `gateway.mode` or `gateway.remote.url` changes.
- The mac app watches `~/.clawdbot/clawdbot.json` and switches modes live when `gateway.mode` or `gateway.remote.url` changes.
- If `gateway.mode` is unset but `gateway.remote.url` is set, the mac app treats it as remote mode.
- Changing connection mode in the mac app writes `gateway.mode` (and `gateway.remote.url` in remote mode) back to the config file.
@@ -45,12 +45,12 @@ Author: steipete · Status: draft spec · Date: 2025-12-20
- Nodes include a `permissions` map in hello/pairing.
- The Gateway surfaces it via `node.list` / `node.describe` so agents can decide what to run.
## CLI (`clawdis`)
- The **only** CLI is `clawdis` (TS/bun). There is no `clawdis-mac` helper.
## CLI (`clawdbot`)
- The **only** CLI is `clawdbot` (TS/bun). There is no `clawdbot-mac` helper.
- For mac‑specific actions, the CLI uses `node.invoke`:
- `clawdis canvas present|navigate|eval|snapshot|a2ui push|a2ui reset`
- `clawdis nodes run --node <id> -- <command...>`
- `clawdis nodes notify --node <id> --title ...`
- `clawdbot canvas present|navigate|eval|snapshot|a2ui push|a2ui reset`
- `clawdbot nodes run --node <id> -- <command...>`
- `clawdbot nodes notify --node <id> --title ...`
## Onboarding
- Install CLI (symlink) → Permissions checklist → Test notification → Done.
@@ -59,19 +59,19 @@ Author: steipete · Status: draft spec · Date: 2025-12-20
## Deep links (URL scheme)
Clawdis (the macOS app) registers a URL scheme for triggering local actions from anywhere (browser, Shortcuts, CLI, etc.).
Clawdbot (the macOS app) registers a URL scheme for triggering local actions from anywhere (browser, Shortcuts, CLI, etc.).
Scheme:
- `clawdis://…`
- `clawdbot://…`
### `clawdis://agent`
### `clawdbot://agent`
Triggers a Gateway `agent` request (same machinery as WebChat/agent runs).
Example:
```bash
open 'clawdis://agent?message=Hello%20from%20deep%20link'
open 'clawdbot://agent?message=Hello%20from%20deep%20link'
```
Query parameters:
@@ -86,16 +86,16 @@ Query parameters:
Safety/guardrails:
- Always enabled.
- Without a `key` query param, the app will prompt for confirmation before invoking the agent.
- With `key=<value>`, Clawdis runs without prompting (intended for personal automations).
- With `key=<value>`, Clawdbot runs without prompting (intended for personal automations).
- The current key is shown in Debug Settings and stored locally in UserDefaults.
Notes:
- In local mode, Clawdis will start the local Gateway if needed before issuing the request.
- In remote mode, Clawdis will use the configured remote tunnel/endpoint.
- In local mode, Clawdbot will start the local Gateway if needed before issuing the request.
- In remote mode, Clawdbot will use the configured remote tunnel/endpoint.
## Build & dev workflow (native)
- `cd native && swift build` (debug) / `swift build -c release`.
- Run app for dev: `swift run Clawdis` (or Xcode scheme).
- Run app for dev: `swift run Clawdbot` (or Xcode scheme).
- Package app + CLI: `scripts/package-mac-app.sh` (builds bun CLI + gateway).
- Tests: add Swift Testing suites under `apps/macos/Tests`.
docs/configuration.md
+72 -56
View File
@@ -1,14 +1,14 @@
---
summary: "All configuration options for ~/.clawdis/clawdis.json with examples"
summary: "All configuration options for ~/.clawdbot/clawdbot.json with examples"
read_when:
- Adding or modifying config fields
---
<!-- {% raw %} -->
# Configuration 🔧
CLAWDIS reads an optional **JSON5** config from `~/.clawdis/clawdis.json` (comments + trailing commas allowed).
CLAWDBOT reads an optional **JSON5** config from `~/.clawdbot/clawdbot.json` (comments + trailing commas allowed).
If the file is missing, CLAWDIS uses safe-ish defaults (embedded Pi agent + per-sender sessions + workspace `~/clawd`). You usually only need a config to:
If the file is missing, CLAWDBOT uses safe-ish defaults (embedded Pi agent + per-sender sessions + workspace `~/clawd`). You usually only need a config to:
- restrict who can trigger the bot (`whatsapp.allowFrom`, `telegram.allowFrom`, etc.)
- control group mention behavior (`whatsapp.groups`, `telegram.groups`, `discord.guilds`, `routing.groupChat`)
- customize message prefixes (`messages`)
@@ -64,7 +64,7 @@ To prevent the bot from responding to WhatsApp @-mentions in groups (only respon
Optional agent identity used for defaults and UX. This is written by the macOS onboarding assistant.
If set, CLAWDIS derives defaults (only when you haven’t set them explicitly):
If set, CLAWDBOT derives defaults (only when you haven’t set them explicitly):
- `messages.responsePrefix` from `identity.emoji`
- `routing.groupChat.mentionPatterns` from `identity.name` (so “@Samantha” works in groups)
@@ -92,8 +92,8 @@ Metadata written by CLI wizards (`onboard`, `configure`, `doctor`, `update`).
### `logging`
- Default log file: `/tmp/clawdis/clawdis-YYYY-MM-DD.log`
- If you want a stable path, set `logging.file` to `/tmp/clawdis/clawdis.log`.
- Default log file: `/tmp/clawdbot/clawdbot-YYYY-MM-DD.log`
- If you want a stable path, set `logging.file` to `/tmp/clawdbot/clawdbot.log`.
- Console output can be tuned separately via:
- `logging.consoleLevel` (defaults to `info`, bumps to `debug` when `--verbose`)
- `logging.consoleStyle` (`pretty` | `compact` | `json`)
@@ -102,7 +102,7 @@ Metadata written by CLI wizards (`onboard`, `configure`, `doctor`, `update`).
{
logging: {
level: "info",
file: "/tmp/clawdis/clawdis.log",
file: "/tmp/clawdbot/clawdbot.log",
consoleLevel: "info",
consoleStyle: "pretty"
}
@@ -208,7 +208,7 @@ Set `web.enabled: false` to keep it off by default.
### `telegram` (bot transport)
Clawdis starts Telegram only when a `telegram` config section exists. The bot token is resolved from `TELEGRAM_BOT_TOKEN` or `telegram.botToken`.
Clawdbot starts Telegram only when a `telegram` config section exists. The bot token is resolved from `TELEGRAM_BOT_TOKEN` or `telegram.botToken`.
Set `telegram.enabled: false` to disable automatic startup.
```json5
@@ -284,7 +284,7 @@ Configure the Discord bot by setting the bot token and optional gating:
}
```
Clawdis starts Discord only when a `discord` config section exists. The token is resolved from `DISCORD_BOT_TOKEN` or `discord.token` (unless `discord.enabled` is `false`). Use `user:<id>` (DM) or `channel:<id>` (guild channel) when specifying delivery targets for cron/CLI commands.
Clawdbot starts Discord only when a `discord` config section exists. The token is resolved from `DISCORD_BOT_TOKEN` or `discord.token` (unless `discord.enabled` is `false`). Use `user:<id>` (DM) or `channel:<id>` (guild channel) when specifying delivery targets for cron/CLI commands.
Guild slugs are lowercase with spaces replaced by `-`; channel keys use the slugged channel name (no leading `#`). Prefer guild ids as keys to avoid rename ambiguity.
Reaction notification modes:
- `off`: no reaction events.
@@ -333,7 +333,7 @@ Slack runs in Socket Mode and requires both a bot token and app token:
}
```
Clawdis starts Slack when the provider is enabled and both tokens are set (via config or `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`). Use `user:<id>` (DM) or `channel:<id>` when specifying delivery targets for cron/CLI commands.
Clawdbot starts Slack when the provider is enabled and both tokens are set (via config or `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`). Use `user:<id>` (DM) or `channel:<id>` when specifying delivery targets for cron/CLI commands.
Reaction notification modes:
- `off`: no reaction events.
@@ -351,7 +351,7 @@ Slack action groups (gate `slack` tool actions):
| emojiList | enabled | Custom emoji list |
### `imessage` (imsg CLI)
Clawdis spawns `imsg rpc` (JSON-RPC over stdio). No daemon or port required.
Clawdbot spawns `imsg rpc` (JSON-RPC over stdio). No daemon or port required.
```json5
{
@@ -395,7 +395,7 @@ Controls inbound/outbound prefixes and timestamps.
```json5
{
messages: {
messagePrefix: "[clawdis]",
messagePrefix: "[clawdbot]",
responsePrefix: "🦞",
timestampPrefix: "Europe/London"
}
@@ -479,7 +479,7 @@ Block streaming:
`agent.model` should be set as `provider/model` (e.g. `anthropic/claude-opus-4-5`).
If `modelAliases` is configured, you may also use the alias key (e.g. `Opus`).
If you omit the provider, CLAWDIS currently assumes `anthropic` as a temporary
If you omit the provider, CLAWDBOT currently assumes `anthropic` as a temporary
deprecation fallback.
Z.AI models are available as `zai/<model>` (e.g. `zai/glm-4.7`) and require
`ZAI_API_KEY` (or legacy `Z_AI_API_KEY`) in the environment.
@@ -534,10 +534,11 @@ non-main sessions so they cannot access your host system.
Defaults (if enabled):
- one container per session
- Debian bookworm-slim based image
- workspace per session under `~/.clawdis/sandboxes`
- workspace per session under `~/.clawdbot/sandboxes`
- auto-prune: idle > 24h OR age > 7d
- tools: allow only `bash`, `process`, `read`, `write`, `edit` (deny wins)
- optional sandboxed browser (Chromium + CDP, noVNC observer)
- hardening knobs: `network`, `user`, `pidsLimit`, `memory`, `cpus`, `ulimits`, `seccompProfile`, `apparmorProfile`
```json5
{
@@ -545,23 +546,35 @@ Defaults (if enabled):
sandbox: {
mode: "non-main", // off | non-main | all
perSession: true,
workspaceRoot: "~/.clawdis/sandboxes",
workspaceRoot: "~/.clawdbot/sandboxes",
docker: {
image: "clawdis-sandbox:bookworm-slim",
containerPrefix: "clawdis-sbx-",
image: "clawdbot-sandbox:bookworm-slim",
containerPrefix: "clawdbot-sbx-",
workdir: "/workspace",
readOnlyRoot: true,
tmpfs: ["/tmp", "/var/tmp", "/run"],
network: "bridge",
network: "none",
user: "1000:1000",
capDrop: ["ALL"],
env: { LANG: "C.UTF-8" },
setupCommand: "apt-get update && apt-get install -y git curl jq"
setupCommand: "apt-get update && apt-get install -y git curl jq",
pidsLimit: 256,
memory: "1g",
memorySwap: "2g",
cpus: 1,
ulimits: {
nofile: { soft: 1024, hard: 2048 },
nproc: 256
},
seccompProfile: "/path/to/seccomp.json",
apparmorProfile: "clawdbot-sandbox",
dns: ["1.1.1.1", "8.8.8.8"],
extraHosts: ["internal.service:10.0.0.5"]
},
browser: {
enabled: false,
image: "clawdis-sandbox-browser:bookworm-slim",
containerPrefix: "clawdis-sbx-browser-",
image: "clawdbot-sandbox-browser:bookworm-slim",
containerPrefix: "clawdbot-sbx-browser-",
cdpPort: 9222,
vncPort: 5900,
noVncPort: 6080,
@@ -586,6 +599,9 @@ Build the default sandbox image once with:
scripts/sandbox-setup.sh
```
Note: sandbox containers default to `network: "none"`; set `agent.sandbox.docker.network`
to `"bridge"` (or your custom network) if the agent needs outbound access.
Build the optional browser image with:
```bash
scripts/sandbox-browser-setup.sh
@@ -599,13 +615,13 @@ URL is injected per session.
### `models` (custom providers + base URLs)
Clawdis uses the **pi-coding-agent** model catalog. You can add custom providers
Clawdbot uses the **pi-coding-agent** model catalog. You can add custom providers
(LiteLLM, local OpenAI-compatible servers, Anthropic proxies, etc.) by writing
`~/.clawdis/agent/models.json` or by defining the same schema inside your
Clawdis config under `models.providers`.
`~/.clawdbot/agent/models.json` or by defining the same schema inside your
Clawdbot config under `models.providers`.
When `models.providers` is present, Clawdis writes/merges a `models.json` into
`~/.clawdis/agent/` on startup:
When `models.providers` is present, Clawdbot writes/merges a `models.json` into
`~/.clawdbot/agent/` on startup:
- default behavior: **merge** (keeps existing providers, overrides on name)
- set `models.mode: "replace"` to overwrite the file contents
@@ -689,7 +705,7 @@ Notes:
- Supported APIs: `openai-completions`, `openai-responses`, `anthropic-messages`,
`google-generative-ai`
- Use `authHeader: true` + `headers` for custom auth needs.
- Override the agent config root with `CLAWDIS_AGENT_DIR` (or `PI_CODING_AGENT_DIR`)
- Override the agent config root with `CLAWDBOT_AGENT_DIR` (or `PI_CODING_AGENT_DIR`)
if you want `models.json` stored elsewhere.
### `session`
@@ -702,7 +718,7 @@ Controls session scoping, idle expiry, reset triggers, and where the session sto
scope: "per-sender",
idleMinutes: 60,
resetTriggers: ["/new", "/reset"],
store: "~/.clawdis/sessions/sessions.json",
store: "~/.clawdbot/sessions/sessions.json",
// mainKey is ignored; primary key is fixed to "main"
agentToAgent: {
// Max ping-pong reply turns between requester/target (0–5).
@@ -726,7 +742,7 @@ Fields:
### `skills` (skills config)
Controls bundled allowlist, install preferences, extra skill folders, and per-skill
overrides. Applies to **bundled** skills and `~/.clawdis/skills` (workspace skills
overrides. Applies to **bundled** skills and `~/.clawdbot/skills` (workspace skills
still win on name conflicts).
Fields:
@@ -774,7 +790,7 @@ Example:
### `browser` (clawd-managed Chrome)
Clawdis can start a **dedicated, isolated** Chrome/Chromium instance for clawd and expose a small loopback control server.
Clawdbot can start a **dedicated, isolated** Chrome/Chromium instance for clawd and expose a small loopback control server.
Profiles can point at a **remote** Chrome via `profiles.<name>.cdpUrl`. Remote
profiles are attach-only (start/stop/reset are disabled).
@@ -786,7 +802,7 @@ Defaults:
- control URL: `http://127.0.0.1:18791` (CDP uses `18792`)
- CDP URL: `http://127.0.0.1:18792` (control URL + 1, legacy single-profile)
- profile color: `#FF4500` (lobster-orange)
- Note: the control server is started by the running gateway (Clawdis.app menubar, or `clawdis gateway`).
- Note: the control server is started by the running gateway (Clawdbot.app menubar, or `clawdbot gateway`).
```json5
{
@@ -839,7 +855,7 @@ Defaults:
mode: "local", // or "remote"
port: 18789, // WS + HTTP multiplex
bind: "loopback",
// controlUi: { enabled: true, basePath: "/clawdis" }
// controlUi: { enabled: true, basePath: "/clawdbot" }
// auth: { mode: "token", token: "your-token" } // token is for multi-machine CLI access
// tailscale: { mode: "off" | "serve" | "funnel" }
}
@@ -848,19 +864,19 @@ Defaults:
Control UI base path:
- `gateway.controlUi.basePath` sets the URL prefix where the Control UI is served.
- Examples: `"/ui"`, `"/clawdis"`, `"/apps/clawdis"`.
- Examples: `"/ui"`, `"/clawdbot"`, `"/apps/clawdbot"`.
- Default: root (`/`) (unchanged).
Notes:
- `clawdis gateway` refuses to start unless `gateway.mode` is set to `local` (or you pass the override flag).
- `clawdbot gateway` refuses to start unless `gateway.mode` is set to `local` (or you pass the override flag).
- `gateway.port` controls the single multiplexed port used for WebSocket + HTTP (control UI, hooks, A2UI).
- Precedence: `--port` > `CLAWDIS_GATEWAY_PORT` > `gateway.port` > default `18789`.
- Precedence: `--port` > `CLAWDBOT_GATEWAY_PORT` > `gateway.port` > default `18789`.
Auth and Tailscale:
- `gateway.auth.mode` sets the handshake requirements (`token` or `password`).
- `gateway.auth.token` stores the shared token for token auth (used by the CLI on the same machine).
- When `gateway.auth.mode` is set, only that method is accepted (plus optional Tailscale headers).
- `gateway.auth.password` can be set here, or via `CLAWDIS_GATEWAY_PASSWORD` (recommended).
- `gateway.auth.password` can be set here, or via `CLAWDBOT_GATEWAY_PASSWORD` (recommended).
- `gateway.auth.allowTailscale` controls whether Tailscale identity headers can satisfy auth.
- `gateway.tailscale.mode: "serve"` uses Tailscale Serve (tailnet only, loopback bind).
- `gateway.tailscale.mode: "funnel"` exposes the dashboard publicly; requires auth.
@@ -872,7 +888,7 @@ Remote client defaults (CLI):
- `gateway.remote.password` supplies the password for remote calls (leave unset for no auth).
macOS app behavior:
- Clawdis.app watches `~/.clawdis/clawdis.json` and switches modes live when `gateway.mode` or `gateway.remote.url` changes.
- Clawdbot.app watches `~/.clawdbot/clawdbot.json` and switches modes live when `gateway.mode` or `gateway.remote.url` changes.
- If `gateway.mode` is unset but `gateway.remote.url` is set, the macOS app treats it as remote mode.
- When you change connection mode in the macOS app, it writes `gateway.mode` (and `gateway.remote.url` in remote mode) back to the config file.
@@ -891,7 +907,7 @@ macOS app behavior:
### `gateway.reload` (Config hot reload)
The Gateway watches `~/.clawdis/clawdis.json` (or `CLAWDIS_CONFIG_PATH`) and applies changes automatically.
The Gateway watches `~/.clawdbot/clawdbot.json` (or `CLAWDBOT_CONFIG_PATH`) and applies changes automatically.
Modes:
- `hybrid` (default): hot-apply safe changes; restart the Gateway for critical changes.
@@ -913,7 +929,7 @@ Modes:
#### Hot reload matrix (files + impact)
Files watched:
- `~/.clawdis/clawdis.json` (or `CLAWDIS_CONFIG_PATH`)
- `~/.clawdbot/clawdbot.json` (or `CLAWDBOT_CONFIG_PATH`)
Hot-applied (no full gateway restart):
- `hooks` (webhook auth/path/mappings) + `hooks.gmail` (Gmail watcher restarted)
@@ -934,16 +950,16 @@ Requires full Gateway restart:
### Multi-instance isolation
To run multiple gateways on one host, isolate per-instance state + config and use unique ports:
- `CLAWDIS_CONFIG_PATH` (per-instance config)
- `CLAWDIS_STATE_DIR` (sessions/creds/logs)
- `CLAWDBOT_CONFIG_PATH` (per-instance config)
- `CLAWDBOT_STATE_DIR` (sessions/creds/logs)
- `agent.workspace` (memories)
- `gateway.port` (unique per instance)
Example:
```bash
CLAWDIS_CONFIG_PATH=~/.clawdis/a.json \
CLAWDIS_STATE_DIR=~/.clawdis-a \
clawdis gateway --port 19001
CLAWDBOT_CONFIG_PATH=~/.clawdbot/a.json \
CLAWDBOT_STATE_DIR=~/.clawdbot-a \
clawdbot gateway --port 19001
```
### `hooks` (Gateway webhooks)
@@ -962,7 +978,7 @@ Defaults:
token: "shared-secret",
path: "/hooks",
presets: ["gmail"],
transformsDir: "~/.clawdis/hooks",
transformsDir: "~/.clawdbot/hooks",
mappings: [
{
match: { path: "gmail" },
@@ -980,7 +996,7 @@ Defaults:
Requests must include the hook token:
- `Authorization: Bearer <token>` **or**
- `x-clawdis-token: <token>` **or**
- `x-clawdbot-token: <token>` **or**
- `?token=<token>`
Endpoints:
@@ -996,7 +1012,7 @@ Mapping notes:
- Templates like `{{messages[0].subject}}` read from the payload.
- `transform` can point to a JS/TS module that returns a hook action.
Gmail helper config (used by `clawdis hooks gmail setup` / `run`):
Gmail helper config (used by `clawdbot hooks gmail setup` / `run`):
```json5
{
@@ -1020,11 +1036,11 @@ Gmail helper config (used by `clawdis hooks gmail setup` / `run`):
Gateway auto-start:
- If `hooks.enabled=true` and `hooks.gmail.account` is set, the Gateway starts
`gog gmail watch serve` on boot and auto-renews the watch.
- Set `CLAWDIS_SKIP_GMAIL_WATCHER=1` to disable the auto-start (for manual runs).
- Set `CLAWDBOT_SKIP_GMAIL_WATCHER=1` to disable the auto-start (for manual runs).
- Avoid running a separate `gog gmail watch serve` alongside the Gateway; it will
fail with `listen tcp 127.0.0.1:8788: bind: address already in use`.
Note: when `tailscale.mode` is on, Clawdis defaults `serve.path` to `/` so
Note: when `tailscale.mode` is on, Clawdbot defaults `serve.path` to `/` so
Tailscale can proxy `/gmail-pubsub` correctly (it strips the set-path prefix).
### `canvasHost` (LAN/tailnet Canvas file server + live reload)
@@ -1038,9 +1054,9 @@ The server listens on the **bridge bind host** (LAN or Tailnet) so nodes can rea
The server:
- serves files under `canvasHost.root`
- injects a tiny live-reload client into served HTML
- watches the directory and broadcasts reloads over a WebSocket endpoint at `/__clawdis/ws`
- watches the directory and broadcasts reloads over a WebSocket endpoint at `/__clawdbot/ws`
- auto-creates a starter `index.html` when the directory is empty (so you see something immediately)
- also serves A2UI at `/__clawdis__/a2ui/` and is advertised to nodes as `canvasHostUrl`
- also serves A2UI at `/__clawdbot__/a2ui/` and is advertised to nodes as `canvasHostUrl`
(always used by nodes for Canvas/A2UI)
Disable live reload (and file watching) if the directory is large or you hit `EMFILE`:
@@ -1058,7 +1074,7 @@ Disable live reload (and file watching) if the directory is large or you hit `EM
Disable with:
- config: `canvasHost: { enabled: false }`
- env: `CLAWDIS_SKIP_CANVAS_HOST=1`
- env: `CLAWDBOT_SKIP_CANVAS_HOST=1`
### `bridge` (node bridge server)
@@ -1087,16 +1103,16 @@ Bind modes:
### `discovery.wideArea` (Wide-Area Bonjour / unicast DNS‑SD)
When enabled, the Gateway writes a unicast DNS-SD zone for `_clawdis-bridge._tcp` under `~/.clawdis/dns/` using the standard discovery domain `clawdis.internal.`
When enabled, the Gateway writes a unicast DNS-SD zone for `_clawdbot-bridge._tcp` under `~/.clawdbot/dns/` using the standard discovery domain `clawdbot.internal.`
To make iOS/Android discover across networks (Vienna ⇄ London), pair this with:
- a DNS server on the gateway host serving `clawdis.internal.` (CoreDNS is recommended)
- Tailscale **split DNS** so clients resolve `clawdis.internal` via that server
- a DNS server on the gateway host serving `clawdbot.internal.` (CoreDNS is recommended)
- Tailscale **split DNS** so clients resolve `clawdbot.internal` via that server
One-time setup helper (gateway host):
```bash
clawdis dns setup --apply
clawdbot dns setup --apply
```
```json5
docs/control-api.md
+2 -2
View File
@@ -5,7 +5,7 @@ read_when:
---
# Control channel API (newline-delimited JSON)
**Deprecated (historical):** superseded by the WebSocket Gateway protocol (`clawdis gateway`, see `docs/architecture.md` and `docs/gateway.md`).
**Deprecated (historical):** superseded by the WebSocket Gateway protocol (`clawdbot gateway`, see `docs/architecture.md` and `docs/gateway.md`).
Current builds use a WebSocket server on `ws://127.0.0.1:18789` and do **not** expose this TCP control channel.
Legacy endpoint (if present in an older build): `127.0.0.1:18789` (TCP, localhost only), typically reached via SSH port forward in remote mode.
@@ -18,7 +18,7 @@ Each line is a JSON object. Two shapes exist:
## Methods
- `ping`: sanity check. Payload: `{ pong: true, ts }`.
- `health`: returns the gateway health snapshot (same shape as `clawdis health --json`).
- `health`: returns the gateway health snapshot (same shape as `clawdbot health --json`).
- `status`: shorter summary (linked/authAge/heartbeatSeconds, session counts).
- `last-heartbeat`: returns the most recent heartbeat event the gateway has seen.
- `set-heartbeats { enabled: boolean }`: toggle heartbeat scheduling.
docs/control-ui.md
+6 -6
View File
@@ -9,7 +9,7 @@ read_when:
The Control UI is a small **Vite + Lit** single-page app served by the Gateway:
- default: `http://<host>:18789/`
- optional prefix: set `gateway.controlUi.basePath` (e.g. `/clawdis`)
- optional prefix: set `gateway.controlUi.basePath` (e.g. `/clawdbot`)
It speaks **directly to the Gateway WebSocket** on the same port.
@@ -27,7 +27,7 @@ The dashboard settings panel lets you store a token; passwords are not persisted
- Cron jobs: list/add/run/enable/disable + run history (`cron.*`)
- Skills: status, enable/disable, install, API key updates (`skills.*`)
- Nodes: list + caps (`node.list`)
- Config: view/edit `~/.clawdis/clawdis.json` (`config.get`, `config.set`)
- Config: view/edit `~/.clawdbot/clawdbot.json` (`config.get`, `config.set`)
- Config schema + form rendering (`config.schema`); Raw JSON editor remains available
- Debug: status/health/models snapshots + event log + manual RPC calls (`status`, `health`, `models.list`)
@@ -38,19 +38,19 @@ The dashboard settings panel lets you store a token; passwords are not persisted
Keep the Gateway on loopback and let Tailscale Serve proxy it with HTTPS:
```bash
clawdis gateway --tailscale serve
clawdbot gateway --tailscale serve
```
Open:
- `https://<magicdns>/` (or your configured `gateway.controlUi.basePath`)
By default, the gateway trusts Tailscale identity headers in serve mode. You can still set
`CLAWDIS_GATEWAY_TOKEN` or `gateway.auth` if you want a shared secret instead.
`CLAWDBOT_GATEWAY_TOKEN` or `gateway.auth` if you want a shared secret instead.
### Bind to tailnet + token (legacy)
```bash
clawdis gateway --bind tailnet --token "$(openssl rand -hex 32)"
clawdbot gateway --bind tailnet --token "$(openssl rand -hex 32)"
```
Then open:
@@ -70,7 +70,7 @@ pnpm ui:build
Optional absolute base (when you want fixed asset URLs):
```bash
CLAWDIS_CONTROL_UI_BASE_PATH=/clawdis/ pnpm ui:build
CLAWDBOT_CONTROL_UI_BASE_PATH=/clawdbot/ pnpm ui:build
```
For local development (separate dev server):
docs/cron.md
+25 -25
View File
@@ -1,5 +1,5 @@
---
summary: "RFC: Cron jobs + wakeups for Clawd/Clawdis (main vs isolated sessions)"
summary: "RFC: Cron jobs + wakeups for Clawd/Clawdbot (main vs isolated sessions)"
read_when:
- Designing scheduled jobs, alarms, or wakeups
- Adding Gateway methods or CLI commands for automation
@@ -13,7 +13,7 @@ Last updated: 2025-12-13
## Context
Clawdis already has:
Clawdbot already has:
- A **gateway heartbeat runner** that runs the agent with `HEARTBEAT` and suppresses `HEARTBEAT_OK` (`src/infra/heartbeat-runner.ts`).
- A lightweight, in-memory **system event queue** (`enqueueSystemEvent`) that is injected into the next **main session** turn (`drainSystemEvents` in `src/auto-reply/reply.ts`).
- A WebSocket **Gateway** daemon that is intended to be always-on (`docs/gateway.md`).
@@ -31,7 +31,7 @@ This RFC adds a small “cron job system” so Clawd can schedule future work an
- `sessionTarget: "isolated"`: run an agent turn in a dedicated session key (job session), optionally delivering a message and/or posting a summary back to main.
- Expose a stable control surface:
- **Gateway methods** (`cron.*`, `wake`) for programmatic usage (mac app, CLI, agents).
- **CLI commands** (`clawdis cron ...`) to add/remove/edit/list and to debug `run`.
- **CLI commands** (`clawdbot cron ...`) to add/remove/edit/list and to debug `run`.
- Produce clear, structured **logs** for job lifecycle and execution outcomes.
## Non-goals (v1)
@@ -90,13 +90,13 @@ Each job is a JSON object with stable keys (unknown keys ignored for forward com
## Storage location
Cron persists everything under `~/.clawdis/cron/`:
- Job store: `~/.clawdis/cron/jobs.json`
- Run history: `~/.clawdis/cron/runs/<jobId>.jsonl`
Cron persists everything under `~/.clawdbot/cron/`:
- Job store: `~/.clawdbot/cron/jobs.json`
- Run history: `~/.clawdbot/cron/runs/<jobId>.jsonl`
You can override the job store path via `cron.store` in config.
The scheduler should never require additional configuration for the base directory (Clawdis already treats `~/.clawdis` as fixed).
The scheduler should never require additional configuration for the base directory (Clawdbot already treats `~/.clawdbot` as fixed).
## Enabling
@@ -109,13 +109,13 @@ To disable it, set:
cron: {
enabled: false,
// optional:
store: "~/.clawdis/cron/jobs.json",
store: "~/.clawdbot/cron/jobs.json",
maxConcurrentRuns: 1
}
}
```
You can also disable scheduling via the environment variable `CLAWDIS_SKIP_CRON=1`.
You can also disable scheduling via the environment variable `CLAWDBOT_SKIP_CRON=1`.
## Scheduler design
@@ -180,7 +180,7 @@ When due:
### “Run in parallel to main”
Clawdis currently serializes command execution through a global in-process queue (`src/process/command-queue.ts`) to avoid collisions.
Clawdbot currently serializes command execution through a global in-process queue (`src/process/command-queue.ts`) to avoid collisions.
To support isolated cron jobs running “in parallel”, we should introduce **lanes** (keyed queues) plus a global concurrency cap:
- Lane `"main"`: inbound auto-replies + main heartbeat.
@@ -253,8 +253,8 @@ The Gateway should broadcast a `cron` event for UI/debug:
Add a `cron` command group (all commands should also support `--json` where sensible):
- `clawdis cron list [--json] [--all]`
- `clawdis cron add ...`
- `clawdbot cron list [--json] [--all]`
- `clawdbot cron add ...`
- schedule flags:
- `--at <iso8601|ms|relative>` (one-shot)
- `--every <duration>` (e.g. `10m`, `1h`)
@@ -266,15 +266,15 @@ Add a `cron` command group (all commands should also support `--json` where sens
- `--system-event "<text>"`
- `--message "<agent message>" [--deliver] [--channel last|whatsapp|telegram|discord|signal|imessage] [--to <dest>]`
- `clawdis cron edit <id> ...` (patch-by-flags, non-interactive)
- `clawdis cron rm <id>`
- `clawdis cron enable <id>` / `clawdis cron disable <id>`
- `clawdis cron run <id> [--force]` (debug)
- `clawdis cron runs --id <id> [--limit <n>]` (run history)
- `clawdis cron status` (scheduler enabled + next wake)
- `clawdbot cron edit <id> ...` (patch-by-flags, non-interactive)
- `clawdbot cron rm <id>`
- `clawdbot cron enable <id>` / `clawdbot cron disable <id>`
- `clawdbot cron run <id> [--force]` (debug)
- `clawdbot cron runs --id <id> [--limit <n>]` (run history)
- `clawdbot cron status` (scheduler enabled + next wake)
Additionally:
- `clawdis wake --mode now|next-heartbeat --text "<text>"` as a thin wrapper around `wake` for agents to call.
- `clawdbot wake --mode now|next-heartbeat --text "<text>"` as a thin wrapper around `wake` for agents to call.
## Examples
@@ -283,7 +283,7 @@ Additionally:
One-shot reminder that targets the main session and triggers a heartbeat immediately at the scheduled time:
```bash
clawdis cron add \
clawdbot cron add \
--at "2025-12-14T07:00:00-08:00" \
--session main \
--wake now \
@@ -295,7 +295,7 @@ clawdis cron add \
Daily at 07:00 in a specific timezone (preferred over “every 24h” to avoid DST drift):
```bash
clawdis cron add \
clawdbot cron add \
--cron "0 7 * * *" \
--tz "America/Los_Angeles" \
--session isolated \
@@ -310,7 +310,7 @@ clawdis cron add \
Every Wednesday at 09:00:
```bash
clawdis cron add \
clawdbot cron add \
--cron "0 9 * * 3" \
--tz "America/Los_Angeles" \
--session isolated \
@@ -325,7 +325,7 @@ clawdis cron add \
Enqueue a note for the main session but let the existing heartbeat cadence pick it up:
```bash
clawdis wake --mode next-heartbeat --text "Next heartbeat: check battery + upcoming meetings."
clawdbot wake --mode next-heartbeat --text "Next heartbeat: check battery + upcoming meetings."
```
## Logging & observability
@@ -345,7 +345,7 @@ Suggested log events:
- `cron: job started` (jobId, scheduleKind, sessionTarget, wakeMode)
- `cron: job finished` (status, durationMs, nextRunAtMs)
- When `cron.enabled` is false, the Gateway logs `cron: disabled` and jobs will not run automatically (the CLI warns on `cron add`/`cron edit`).
- Use `clawdis cron status` to confirm the scheduler is enabled and see the next wake time.
- Use `clawdbot cron status` to confirm the scheduler is enabled and see the next wake time.
## Safety & security
@@ -363,7 +363,7 @@ Suggested log events:
- lane concurrency: main vs cron overlap is bounded
- “wake now” coalescing and pending behavior when provider not ready
- Integration tests:
- start Gateway with `CLAWDIS_SKIP_PROVIDERS=1`, add jobs, list/edit/remove
- start Gateway with `CLAWDBOT_SKIP_PROVIDERS=1`, add jobs, list/edit/remove
- simulate due jobs and assert `enqueueSystemEvent` called + cron events broadcast
## Rollout plan
docs/device-models.md
+7 -7
View File
@@ -1,5 +1,5 @@
---
summary: "How Clawdis vendors Apple device model identifiers for friendly names in the macOS app."
summary: "How Clawdbot vendors Apple device model identifiers for friendly names in the macOS app."
read_when:
- Updating device model identifier mappings or NOTICE/license files
- Changing how Instances UI displays device names
@@ -11,7 +11,7 @@ The macOS companion app shows friendly Apple device model names in the **Instanc
The mapping is vendored as JSON under:
- `apps/macos/Sources/Clawdis/Resources/DeviceModels/`
- `apps/macos/Sources/Clawdbot/Resources/DeviceModels/`
## Data source
@@ -19,12 +19,12 @@ We currently vendor the mapping from the MIT-licensed repository:
- `kyle-seongwoo-jun/apple-device-identifiers`
To keep builds deterministic, the JSON files are pinned to specific upstream commits (recorded in `apps/macos/Sources/Clawdis/Resources/DeviceModels/NOTICE.md`).
To keep builds deterministic, the JSON files are pinned to specific upstream commits (recorded in `apps/macos/Sources/Clawdbot/Resources/DeviceModels/NOTICE.md`).
## Updating the database
1. Pick the upstream commits you want to pin to (one for iOS, one for macOS).
2. Update the commit hashes in `apps/macos/Sources/Clawdis/Resources/DeviceModels/NOTICE.md`.
2. Update the commit hashes in `apps/macos/Sources/Clawdbot/Resources/DeviceModels/NOTICE.md`.
3. Re-download the JSON files, pinned to those commits:
```bash
@@ -32,13 +32,13 @@ IOS_COMMIT="<commit sha for ios-device-identifiers.json>"
MAC_COMMIT="<commit sha for mac-device-identifiers.json>"
curl -fsSL "https://raw.githubusercontent.com/kyle-seongwoo-jun/apple-device-identifiers/${IOS_COMMIT}/ios-device-identifiers.json" \
-o apps/macos/Sources/Clawdis/Resources/DeviceModels/ios-device-identifiers.json
-o apps/macos/Sources/Clawdbot/Resources/DeviceModels/ios-device-identifiers.json
curl -fsSL "https://raw.githubusercontent.com/kyle-seongwoo-jun/apple-device-identifiers/${MAC_COMMIT}/mac-device-identifiers.json" \
-o apps/macos/Sources/Clawdis/Resources/DeviceModels/mac-device-identifiers.json
-o apps/macos/Sources/Clawdbot/Resources/DeviceModels/mac-device-identifiers.json
```
4. Ensure `apps/macos/Sources/Clawdis/Resources/DeviceModels/LICENSE.apple-device-identifiers.txt` still matches upstream (replace it if the upstream license changes).
4. Ensure `apps/macos/Sources/Clawdbot/Resources/DeviceModels/LICENSE.apple-device-identifiers.txt` still matches upstream (replace it if the upstream license changes).
5. Verify the macOS app builds cleanly (no warnings):
```bash
docs/discord.md
+5 -5
View File
@@ -10,7 +10,7 @@ Updated: 2025-12-07
Status: ready for DM and guild text channels via the official Discord bot gateway.
## Goals
- Talk to Clawdis via Discord DMs or guild channels.
- Talk to Clawdbot via Discord DMs or guild channels.
- Share the same `main` session used by WhatsApp/Telegram/WebChat; guild channels stay isolated as `discord:group:<channelId>` (display names use `discord:<guildSlug>#<channelSlug>`).
- Group DMs are ignored by default; enable via `discord.dm.groupEnabled` and optionally restrict by `discord.dm.groupChannels`.
- Keep routing deterministic: replies always go back to the surface they arrived on.
@@ -18,9 +18,9 @@ Status: ready for DM and guild text channels via the official Discord bot gatewa
## How it works
1. Create a Discord application → Bot, enable the intents you need (DMs + guild messages + message content), and grab the bot token.
2. Invite the bot to your server with the permissions required to read/send messages where you want to use it.
3. Configure Clawdis with `DISCORD_BOT_TOKEN` (or `discord.token` in `~/.clawdis/clawdis.json`).
3. Configure Clawdbot with `DISCORD_BOT_TOKEN` (or `discord.token` in `~/.clawdbot/clawdbot.json`).
4. Run the gateway; it auto-starts the Discord provider only when a `discord` config section exists **and** the token is set (unless `discord.enabled = false`).
- If you prefer env vars, still add `discord: { enabled: true }` to `~/.clawdis/clawdis.json` and set `DISCORD_BOT_TOKEN`.
- If you prefer env vars, still add `discord: { enabled: true }` to `~/.clawdbot/clawdbot.json` and set `DISCORD_BOT_TOKEN`.
5. Direct chats: use `user:<id>` (or a `<@id>` mention) when delivering; all turns land in the shared `main` session.
6. Guild channels: use `channel:<channelId>` for delivery. Mentions are required by default and can be set per guild or per channel.
7. Optional DM control: set `discord.dm.enabled = false` to ignore all DMs, or `discord.dm.allowFrom` to allow specific users (ids or names). Use `discord.dm.groupEnabled` + `discord.dm.groupChannels` to allow group DMs.
@@ -167,7 +167,7 @@ Slash command notes:
- Register a chat input command in Discord with at least one string option (e.g., `prompt`).
- The first non-empty string option is treated as the prompt.
- Slash commands honor the same allowlists as DMs/guild messages (`discord.dm.allowFrom`, `discord.guilds`, per-channel rules).
- Clawdis will auto-register `/clawd` (or the configured name) if it doesn't already exist.
- Clawdbot will auto-register `/clawd` (or the configured name) if it doesn't already exist.
## Tool actions
The agent can call `discord` with actions like:
@@ -186,4 +186,4 @@ Emoji can be unicode (e.g., `✅`) or custom emoji syntax like `<:party_blob:123
## Safety & ops
- Treat the bot token like a password; prefer the `DISCORD_BOT_TOKEN` env var on supervised hosts or lock down the config file permissions.
- Only grant the bot permissions it needs (typically Read/Send Messages).
- If the bot is stuck or rate limited, restart the gateway (`clawdis gateway --force`) after confirming no other processes own the Discord session.
- If the bot is stuck or rate limited, restart the gateway (`clawdbot gateway --force`) after confirming no other processes own the Discord session.
docs/discovery.md
+11 -11
View File
@@ -7,12 +7,12 @@ read_when:
---
# Discovery & transports
Clawdis has two distinct problems that look similar on the surface:
Clawdbot has two distinct problems that look similar on the surface:
1) **Operator remote control**: the macOS menu bar app controlling a gateway running elsewhere.
2) **Node pairing**: iOS/Android (and future nodes) finding a gateway and pairing securely.
The design goal is to keep all network discovery/advertising in the **Node Gateway** (`clawd` / `clawdis gateway`) and keep clients (mac app, iOS) as consumers.
The design goal is to keep all network discovery/advertising in the **Node Gateway** (`clawd` / `clawdbot gateway`) and keep clients (mac app, iOS) as consumers.
## Terms
@@ -47,24 +47,24 @@ Troubleshooting and beacon details: `docs/bonjour.md`.
#### Current implementation
- Service types:
- `_clawdis-bridge._tcp` (bridge transport beacon)
- `_clawdbot-bridge._tcp` (bridge transport beacon)
- TXT keys (non-secret):
- `role=gateway`
- `lanHost=<hostname>.local`
- `sshPort=22` (or whatever is advertised)
- `gatewayPort=18789` (loopback WS port; informational)
- `bridgePort=18790` (when bridge is enabled)
- `canvasPort=18793` (default canvas host port; serves `/__clawdis__/canvas/`)
- `cliPath=<path>` (optional; absolute path to a runnable `clawdis` entrypoint or binary)
- `canvasPort=18793` (default canvas host port; serves `/__clawdbot__/canvas/`)
- `cliPath=<path>` (optional; absolute path to a runnable `clawdbot` entrypoint or binary)
- `tailnetDns=<magicdns>` (optional hint; auto-detected when Tailscale is available)
Disable/override:
- `CLAWDIS_DISABLE_BONJOUR=1` disables advertising.
- `CLAWDIS_BRIDGE_ENABLED=0` disables the bridge listener.
- `bridge.bind` / `bridge.port` in `~/.clawdis/clawdis.json` control bridge bind/port (preferred).
- `CLAWDIS_BRIDGE_HOST` / `CLAWDIS_BRIDGE_PORT` still work as a back-compat override when `bridge.bind` / `bridge.port` are not set.
- `CLAWDIS_SSH_PORT` overrides the SSH port advertised in the bridge beacon (defaults to 22).
- `CLAWDIS_TAILNET_DNS` publishes a `tailnetDns` hint (MagicDNS) in the bridge beacon (auto-detected if unset).
- `CLAWDBOT_DISABLE_BONJOUR=1` disables advertising.
- `CLAWDBOT_BRIDGE_ENABLED=0` disables the bridge listener.
- `bridge.bind` / `bridge.port` in `~/.clawdbot/clawdbot.json` control bridge bind/port (preferred).
- `CLAWDBOT_BRIDGE_HOST` / `CLAWDBOT_BRIDGE_PORT` still work as a back-compat override when `bridge.bind` / `bridge.port` are not set.
- `CLAWDBOT_SSH_PORT` overrides the SSH port advertised in the bridge beacon (defaults to 22).
- `CLAWDBOT_TAILNET_DNS` publishes a `tailnetDns` hint (MagicDNS) in the bridge beacon (auto-detected if unset).
### 2) Tailnet (cross-network)
docs/docker.md
+37 -20
View File
@@ -1,5 +1,5 @@
---
summary: "Optional Docker-based setup and onboarding for Clawdis"
summary: "Optional Docker-based setup and onboarding for Clawdbot"
read_when:
- You want a containerized gateway instead of local installs
- You are validating the Docker flow
@@ -10,7 +10,7 @@ read_when:
Docker is **optional**. Use it only if you want a containerized gateway or to validate the Docker flow.
This guide covers:
- Containerized Gateway (full Clawdis in Docker)
- Containerized Gateway (full Clawdbot in Docker)
- Per-session Agent Sandbox (host gateway + Docker-isolated agent tools)
## Requirements
@@ -35,22 +35,22 @@ This script:
- starts the gateway via Docker Compose
It writes config/workspace on the host:
- `~/.clawdis/`
- `~/.clawdbot/`
- `~/clawd`
### Manual flow (compose)
```bash
docker build -t clawdis:local -f Dockerfile .
docker compose run --rm clawdis-cli onboard
docker compose run --rm clawdis-cli login
docker compose up -d clawdis-gateway
docker build -t clawdbot:local -f Dockerfile .
docker compose run --rm clawdbot-cli onboard
docker compose run --rm clawdbot-cli login
docker compose up -d clawdbot-gateway
```
### Health check
```bash
docker compose exec clawdis-gateway node dist/index.js health --token "$CLAWDIS_GATEWAY_TOKEN"
docker compose exec clawdbot-gateway node dist/index.js health --token "$CLAWDBOT_GATEWAY_TOKEN"
```
### E2E smoke test (Docker)
@@ -62,7 +62,7 @@ scripts/e2e/onboard-docker.sh
### Notes
- Gateway bind defaults to `lan` for container use.
- The gateway container is the source of truth for sessions (`~/.clawdis/sessions`).
- The gateway container is the source of truth for sessions (`~/.clawdbot/sessions`).
## Per-session Agent Sandbox (host gateway + Docker tools)
@@ -76,10 +76,11 @@ container. The gateway stays on your host, but the tool execution is isolated:
### Default behavior
- Image: `clawdis-sandbox:bookworm-slim`
- Image: `clawdbot-sandbox:bookworm-slim`
- One container per session
- Workspace per session under `~/.clawdis/sandboxes`
- Workspace per session under `~/.clawdbot/sandboxes`
- Auto-prune: idle > 24h OR age > 7d
- Network: `none` by default (explicitly opt-in if you need egress)
- Default allow: `bash`, `process`, `read`, `write`, `edit`
- Default deny: `browser`, `canvas`, `nodes`, `cron`, `discord`, `gateway`
@@ -91,17 +92,29 @@ container. The gateway stays on your host, but the tool execution is isolated:
sandbox: {
mode: "non-main", // off | non-main | all
perSession: true,
workspaceRoot: "~/.clawdis/sandboxes",
workspaceRoot: "~/.clawdbot/sandboxes",
docker: {
image: "clawdis-sandbox:bookworm-slim",
image: "clawdbot-sandbox:bookworm-slim",
workdir: "/workspace",
readOnlyRoot: true,
tmpfs: ["/tmp", "/var/tmp", "/run"],
network: "bridge",
network: "none",
user: "1000:1000",
capDrop: ["ALL"],
env: { LANG: "C.UTF-8" },
setupCommand: "apt-get update && apt-get install -y git curl jq"
setupCommand: "apt-get update && apt-get install -y git curl jq",
pidsLimit: 256,
memory: "1g",
memorySwap: "2g",
cpus: 1,
ulimits: {
nofile: { soft: 1024, hard: 2048 },
nproc: 256
},
seccompProfile: "/path/to/seccomp.json",
apparmorProfile: "clawdbot-sandbox",
dns: ["1.1.1.1", "8.8.8.8"],
extraHosts: ["internal.service:10.0.0.5"]
},
tools: {
allow: ["bash", "process", "read", "write", "edit"],
@@ -116,13 +129,17 @@ container. The gateway stays on your host, but the tool execution is isolated:
}
```
Hardening knobs live under `agent.sandbox.docker`:
`network`, `user`, `pidsLimit`, `memory`, `memorySwap`, `cpus`, `ulimits`,
`seccompProfile`, `apparmorProfile`, `dns`, `extraHosts`.
### Build the default sandbox image
```bash
scripts/sandbox-setup.sh
```
This builds `clawdis-sandbox:bookworm-slim` using `Dockerfile.sandbox`.
This builds `clawdbot-sandbox:bookworm-slim` using `Dockerfile.sandbox`.
### Sandbox browser image
@@ -132,7 +149,7 @@ To run the browser tool inside the sandbox, build the browser image:
scripts/sandbox-browser-setup.sh
```
This builds `clawdis-sandbox-browser:bookworm-slim` using
This builds `clawdbot-sandbox-browser:bookworm-slim` using
`Dockerfile.sandbox-browser`. The container runs Chromium with CDP enabled and
an optional noVNC observer (headful via Xvfb).
@@ -158,7 +175,7 @@ Custom browser image:
```json5
{
agent: {
sandbox: { browser: { image: "my-clawdis-browser" } }
sandbox: { browser: { image: "my-clawdbot-browser" } }
}
}
```
@@ -176,13 +193,13 @@ Prune rules (`agent.sandbox.prune`) apply to browser containers too.
Build your own image and point config to it:
```bash
docker build -t my-clawdis-sbx -f Dockerfile.sandbox .
docker build -t my-clawdbot-sbx -f Dockerfile.sandbox .
```
```json5
{
agent: {
sandbox: { docker: { image: "my-clawdis-sbx" } }
sandbox: { docker: { image: "my-clawdbot-sbx" } }
}
}
```
docs/docs.json
+3 -3
View File
@@ -1,6 +1,6 @@
{
"$schema": "https://mintlify.com/docs.json",
"name": "Clawdis",
"name": "Clawdbot",
"theme": "mint",
"logo": {
"light": "/assets/pixel-lobster.svg",
@@ -13,11 +13,11 @@
"topbarLinks": [
{
"name": "GitHub",
"url": "https://github.com/steipete/clawdis"
"url": "https://github.com/clawdbot/clawdbot"
},
{
"name": "Releases",
"url": "https://github.com/steipete/clawdis/releases"
"url": "https://github.com/clawdbot/clawdbot/releases"
}
],
"navigation": {
docs/doctor.md
+5 -5
View File
@@ -6,7 +6,7 @@ read_when:
---
# Doctor
`clawdis doctor` is the repair + migration tool for Clawdis. It runs a quick health check, audits skills, and can migrate deprecated config entries to the new schema.
`clawdbot doctor` is the repair + migration tool for Clawdbot. It runs a quick health check, audits skills, and can migrate deprecated config entries to the new schema.
## What it does
- Runs a health check and offers to restart the gateway if it looks unhealthy.
@@ -14,11 +14,11 @@ read_when:
- Detects deprecated config keys and offers to migrate them.
## Legacy config migrations
When the config contains deprecated keys, other commands will refuse to run and ask you to run `clawdis doctor`.
When the config contains deprecated keys, other commands will refuse to run and ask you to run `clawdbot doctor`.
Doctor will:
- Explain which legacy keys were found.
- Show the migration it applied.
- Rewrite `~/.clawdis/clawdis.json` with the updated schema.
- Rewrite `~/.clawdbot/clawdbot.json` with the updated schema.
Current migrations:
- `routing.allowFrom` → `whatsapp.allowFrom`
@@ -26,11 +26,11 @@ Current migrations:
## Usage
```bash
clawdis doctor
clawdbot doctor
```
If you want to review changes before writing, open the config file first:
```bash
cat ~/.clawdis/clawdis.json
cat ~/.clawdbot/clawdbot.json
```
docs/faq.md
+70 -70
View File
@@ -1,5 +1,5 @@
---
summary: "Frequently asked questions about Clawdis setup, configuration, and usage"
summary: "Frequently asked questions about Clawdbot setup, configuration, and usage"
---
# FAQ 🦞
@@ -7,20 +7,20 @@ Common questions from the community. For detailed configuration, see [configurat
## Installation & Setup
### Where does Clawdis store its data?
### Where does Clawdbot store its data?
Everything lives under `~/.clawdis/`:
Everything lives under `~/.clawdbot/`:
| Path | Purpose |
|------|---------|
| `~/.clawdis/clawdis.json` | Main config (JSON5) |
| `~/.clawdis/credentials/` | WhatsApp/Telegram auth tokens |
| `~/.clawdis/sessions/` | Conversation history & state |
| `~/.clawdis/sessions/sessions.json` | Session metadata |
| `~/.clawdbot/clawdbot.json` | Main config (JSON5) |
| `~/.clawdbot/credentials/` | WhatsApp/Telegram auth tokens |
| `~/.clawdbot/sessions/` | Conversation history & state |
| `~/.clawdbot/sessions/sessions.json` | Session metadata |
Your **workspace** (AGENTS.md, memory files, skills) is separate — configured via `agent.workspace` in your config (default: `~/clawd`).
### What platforms does Clawdis run on?
### What platforms does Clawdbot run on?
**macOS and Linux** are the primary targets. Anywhere Node.js 22+ runs should work in theory.
@@ -30,7 +30,7 @@ Your **workspace** (AGENTS.md, memory files, skills) is separate — configured
Some features are platform-specific:
- **iMessage** — macOS only (uses `imsg` CLI)
- **Clawdis.app** — macOS native app (optional, gateway works without it)
- **Clawdbot.app** — macOS native app (optional, gateway works without it)
### What are the minimum system requirements?
@@ -38,12 +38,12 @@ Some features are platform-specific:
- **RAM:** 512MB-1GB is enough (community member runs on 1GB VPS!)
- **CPU:** 1 core is fine for personal use
- **Disk:** ~500MB for Clawdis + deps, plus space for logs/media
- **Disk:** ~500MB for Clawdbot + deps, plus space for logs/media
The gateway is just shuffling messages around. A Raspberry Pi 4 can run it. You can also use **Bun** instead of Node for even lower memory footprint:
```bash
bun clawdis gateway
bun clawdbot gateway
```
### How do I install on Linux without Homebrew?
@@ -64,23 +64,23 @@ Most of Peter's tools are Go binaries — clone, build, move to PATH. No brew ne
You need a config file. Run the onboarding wizard:
```bash
pnpm clawdis onboard
pnpm clawdbot onboard
```
This creates `~/.clawdis/clawdis.json` with your API keys, workspace path, and owner phone number.
This creates `~/.clawdbot/clawdbot.json` with your API keys, workspace path, and owner phone number.
### How do I start fresh?
```bash
# Backup first (optional)
cp -r ~/.clawdis ~/.clawdis-backup
cp -r ~/.clawdbot ~/.clawdbot-backup
# Remove config and credentials
rm -rf ~/.clawdis
rm -rf ~/.clawdbot
# Re-run onboarding
pnpm clawdis onboard
pnpm clawdis login
pnpm clawdbot onboard
pnpm clawdbot login
```
### Something's broken — how do I diagnose?
@@ -88,14 +88,14 @@ pnpm clawdis login
Run the doctor:
```bash
pnpm clawdis doctor
pnpm clawdbot doctor
```
It checks your config, skills status, and gateway health. It can also restart the gateway daemon if needed.
### Terminal onboarding vs macOS app?
**Use terminal onboarding** (`pnpm clawdis onboard`) — it's more stable right now.
**Use terminal onboarding** (`pnpm clawdbot onboard`) — it's more stable right now.
The macOS app onboarding is still being polished and can have quirks (e.g., WhatsApp 515 errors, OAuth issues).
@@ -113,10 +113,10 @@ They're **separate billing**! An API key does NOT use your subscription.
**For OAuth:** During onboarding, pick "Anthropic OAuth", log in to your Claude account, paste the code back. Or just run:
```bash
pnpm clawdis login
pnpm clawdbot login
```
**If OAuth fails** (headless/container): Do OAuth on a normal machine, then copy `~/.clawdis/` to your server. The auth is just a JSON file.
**If OAuth fails** (headless/container): Do OAuth on a normal machine, then copy `~/.clawdbot/` to your server. The auth is just a JSON file.
### Does enterprise OAuth work?
@@ -128,7 +128,7 @@ pnpm clawdis login
OAuth needs the callback to reach the machine running the CLI. Options:
1. **Copy auth manually** — Run OAuth on your laptop, copy `~/.clawdis/credentials/` to the container.
1. **Copy auth manually** — Run OAuth on your laptop, copy `~/.clawdbot/credentials/` to the container.
2. **SSH tunnel** — `ssh -L 18789:localhost:18789 user@server`
3. **Tailscale** — Put both machines on your tailnet.
@@ -136,12 +136,12 @@ OAuth needs the callback to reach the machine running the CLI. Options:
## Migration & Deployment
### How do I migrate Clawdis to a new machine (or VPS)?
### How do I migrate Clawdbot to a new machine (or VPS)?
1. **Backup on old machine:**
```bash
# Config + credentials + sessions
tar -czvf clawdis-backup.tar.gz ~/.clawdis
tar -czvf clawdbot-backup.tar.gz ~/.clawdbot
# Your workspace (memories, AGENTS.md, etc.)
tar -czvf workspace-backup.tar.gz ~/path/to/workspace
@@ -149,39 +149,39 @@ OAuth needs the callback to reach the machine running the CLI. Options:
2. **Copy to new machine:**
```bash
scp clawdis-backup.tar.gz workspace-backup.tar.gz user@new-machine:~/
scp clawdbot-backup.tar.gz workspace-backup.tar.gz user@new-machine:~/
```
3. **Restore on new machine:**
```bash
cd ~
tar -xzvf clawdis-backup.tar.gz
tar -xzvf clawdbot-backup.tar.gz
tar -xzvf workspace-backup.tar.gz
```
4. **Install Clawdis** (Node 22+, pnpm, clone repo, `pnpm install && pnpm build`)
4. **Install Clawdbot** (Node 22+, pnpm, clone repo, `pnpm install && pnpm build`)
5. **Start gateway:**
```bash
pnpm clawdis gateway
pnpm clawdbot gateway
```
**Note:** WhatsApp may notice the IP change and require re-authentication. If so, run `pnpm clawdis login` again. Stop the old instance before starting the new one to avoid conflicts.
**Note:** WhatsApp may notice the IP change and require re-authentication. If so, run `pnpm clawdbot login` again. Stop the old instance before starting the new one to avoid conflicts.
### Can I run Clawdis in Docker?
### Can I run Clawdbot in Docker?
There's no official Docker setup yet, but it works. Key considerations:
- **WhatsApp login:** QR code works in terminal — no display needed.
- **Persistence:** Mount `~/.clawdis/` and your workspace as volumes.
- **Persistence:** Mount `~/.clawdbot/` and your workspace as volumes.
- **pnpm doesn't persist:** Global npm installs don't survive container restarts. Install pnpm in your startup script.
- **Browser automation:** Optional. If needed, install headless Chrome + Playwright deps, or connect to a remote browser via `--remote-debugging-port`.
**Volume mappings (e.g., Unraid):**
```
/mnt/user/appdata/clawdis/config → /root/.clawdis
/mnt/user/appdata/clawdis/workspace → /root/clawd
/mnt/user/appdata/clawdis/app → /app
/mnt/user/appdata/clawdbot/config → /root/.clawdbot
/mnt/user/appdata/clawdbot/workspace → /root/clawd
/mnt/user/appdata/clawdbot/app → /app
```
**Startup script (`start.sh`):**
@@ -189,7 +189,7 @@ There's no official Docker setup yet, but it works. Key considerations:
#!/bin/bash
npm install -g pnpm
cd /app
pnpm clawdis gateway
pnpm clawdbot gateway
```
**Container command:**
@@ -199,7 +199,7 @@ bash /app/start.sh
Docker support is on the roadmap — PRs welcome!
### Can I run Clawdis headless on a VPS?
### Can I run Clawdbot headless on a VPS?
Yes! The terminal QR code login works fine over SSH. For long-running operation:
@@ -208,13 +208,13 @@ Yes! The terminal QR code login works fine over SSH. For long-running operation:
### bun binary vs Node runtime?
Clawdis can run as:
Clawdbot can run as:
- **bun binary** — Single executable, easy distribution, auto-restarts via launchd
- **Node runtime** (`pnpm clawdis gateway`) — More stable for WhatsApp
- **Node runtime** (`pnpm clawdbot gateway`) — More stable for WhatsApp
If you see WebSocket errors like `ws.WebSocket 'upgrade' event is not implemented`, use Node instead of the bun binary. Bun's WebSocket implementation has edge cases that can break WhatsApp (Baileys).
**For stability:** Use launchd (macOS) or the Clawdis.app — they handle process supervision (auto-restart on crash).
**For stability:** Use launchd (macOS) or the Clawdbot.app — they handle process supervision (auto-restart on crash).
**For debugging:** Use `pnpm gateway:watch` for live reload during development.
@@ -226,7 +226,7 @@ This is often the bun WebSocket issue. Workaround:
```bash
pnpm gateway:watch
```
2. In **Clawdis.app → Settings → Debug**, check **"External gateway"**
2. In **Clawdbot.app → Settings → Debug**, check **"External gateway"**
3. The app now connects to your Node gateway instead of spawning bun
This is the most stable setup until bun's WebSocket handling improves.
@@ -246,7 +246,7 @@ The intended design is **one Clawd, one identity**. Rather than running separate
Why? A unified assistant knows your whole context. Your fitness coach knows when you've had a stressful work week.
If you truly need full separation (different users, privacy boundaries), you'd need:
- Separate config + state directories (`CLAWDIS_CONFIG_PATH`, `CLAWDIS_STATE_DIR`)
- Separate config + state directories (`CLAWDBOT_CONFIG_PATH`, `CLAWDBOT_STATE_DIR`)
- Separate agent workspaces (`agent.workspace`)
- Separate gateway ports (`gateway.port` / `--port`)
- Separate phone numbers for WhatsApp (one number = one account)
@@ -259,7 +259,7 @@ Currently, sessions are per-chat:
**Workaround:** Create multiple groups (even just you + the bot) for different contexts. Each group maintains its own session.
Feature request? Open a [GitHub discussion](https://github.com/steipete/clawdis/discussions)!
Feature request? Open a [GitHub discussion](https://github.com/clawdbot/clawdbot/discussions)!
### How do groups work?
@@ -275,9 +275,9 @@ See [groups.md](./groups.md) for details.
## Context & Memory
### How much context can Clawdis handle?
### How much context can Clawdbot handle?
Claude Opus has a 200k token context window, and Clawdis uses **autocompaction** — older conversation gets summarized to stay under the limit.
Claude Opus has a 200k token context window, and Clawdbot uses **autocompaction** — older conversation gets summarized to stay under the limit.
Practical tips:
- Keep `AGENTS.md` focused, not bloated.
@@ -293,14 +293,14 @@ In your workspace directory (configured in `agent.workspace`, default `~/clawd`)
Check your config:
```bash
cat ~/.clawdis/clawdis.json | grep workspace
cat ~/.clawdbot/clawdbot.json | grep workspace
```
---
## Platforms
### Which platforms does Clawdis support?
### Which platforms does Clawdbot support?
- **WhatsApp** — Primary. Uses WhatsApp Web protocol.
- **Telegram** — Via Bot API (grammY).
@@ -350,8 +350,8 @@ Not all models support images! Check `agent.model` in your config:
**2. Is media being downloaded?**
```bash
ls -la ~/.clawdis/media/inbound/
grep -i "media\|download" /tmp/clawdis/clawdis-*.log | tail -20
ls -la ~/.clawdbot/media/inbound/
grep -i "media\|download" /tmp/clawdbot/clawdbot-*.log | tail -20
```
**3. Is `agent.mediaMaxMb` too low?**
@@ -368,7 +368,7 @@ Use the [summarize](https://summarize.sh) skill to extract and condense content
### Can I use multiple platforms at once?
Yes! One Clawdis gateway can connect to WhatsApp, Telegram, Discord, and more simultaneously. Each platform maintains its own sessions.
Yes! One Clawdbot gateway can connect to WhatsApp, Telegram, Discord, and more simultaneously. Each platform maintains its own sessions.
### WhatsApp: Can I use two numbers?
@@ -391,13 +391,13 @@ No gateway restart needed!
Use **[Tailscale](https://tailscale.com/)** to create a secure network between your machines:
1. Install Tailscale on all machines (it's separate from Clawdis — set it up yourself)
1. Install Tailscale on all machines (it's separate from Clawdbot — set it up yourself)
2. Each gets a stable IP (like `100.x.x.x`)
3. SSH just works: `ssh user@100.x.x.x "command"`
Clawdis can use Tailscale when you set `bridge.bind: "tailnet"` in your config — it auto-detects your Tailscale IP.
Clawdbot can use Tailscale when you set `bridge.bind: "tailnet"` in your config — it auto-detects your Tailscale IP.
For deeper integration, look into **Clawdis nodes** — pair remote machines with your gateway for camera/screen/automation access.
For deeper integration, look into **Clawdbot nodes** — pair remote machines with your gateway for camera/screen/automation access.
---
@@ -408,8 +408,8 @@ For deeper integration, look into **Clawdis nodes** — pair remote machines wit
If you hit build errors on `main`:
1. Pull latest: `git pull origin main && pnpm install`
2. Try `pnpm clawdis doctor`
3. Check [GitHub issues](https://github.com/steipete/clawdis/issues) or Discord
2. Try `pnpm clawdbot doctor`
3. Check [GitHub issues](https://github.com/clawdbot/clawdbot/issues) or Discord
4. Temporary workaround: checkout an older commit
### WhatsApp logged me out
@@ -417,7 +417,7 @@ If you hit build errors on `main`:
WhatsApp sometimes disconnects on IP changes or after updates. Re-authenticate:
```bash
pnpm clawdis login
pnpm clawdbot login
```
Scan the QR code and you're back.
@@ -426,7 +426,7 @@ Scan the QR code and you're back.
Check logs:
```bash
cat /tmp/clawdis/clawdis-$(date +%Y-%m-%d).log
cat /tmp/clawdbot/clawdbot-$(date +%Y-%m-%d).log
```
Common issues:
@@ -442,8 +442,8 @@ pnpm gateway:watch
**Pro tip:** Use Codex to debug:
```bash
cd ~/path/to/clawdis
codex --full-auto "debug why clawdis gateway won't start"
cd ~/path/to/clawdbot
codex --full-auto "debug why clawdbot gateway won't start"
```
### Processes keep restarting after I kill them (Linux)
@@ -452,8 +452,8 @@ Something is supervising them. Check:
```bash
# systemd?
systemctl list-units | grep -i clawdis
sudo systemctl stop clawdis
systemctl list-units | grep -i clawdbot
sudo systemctl stop clawdbot
# pm2?
pm2 list
@@ -466,20 +466,20 @@ Stop the supervisor first, then the processes.
```bash
# Stop processes
pkill -f "clawdis"
pkill -f "clawdbot"
# If using systemd
sudo systemctl stop clawdis
sudo systemctl disable clawdis
sudo systemctl stop clawdbot
sudo systemctl disable clawdbot
# Remove data
rm -rf ~/.clawdis
rm -rf ~/.clawdbot
# Remove repo and re-clone
rm -rf ~/clawdis
git clone https://github.com/steipete/clawdis.git
cd clawdis && pnpm install && pnpm build
pnpm clawdis onboard
rm -rf ~/clawdbot
git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot && pnpm install && pnpm build
pnpm clawdbot onboard
```
---
@@ -509,7 +509,7 @@ Use `/model` to switch without restarting:
/model opus
```
**Setup:** Configure allowed models and aliases in `clawdis.json`:
**Setup:** Configure allowed models and aliases in `clawdbot.json`:
```json
{
@@ -614,4 +614,4 @@ If you tend to send multiple short messages, `/queue instant` feels most natural
---
*Still stuck? Ask in [Discord](https://discord.gg/qkhbAGHRBT) or open a [GitHub discussion](https://github.com/steipete/clawdis/discussions).* 🦞
*Still stuck? Ask in [Discord](https://discord.gg/qkhbAGHRBT) or open a [GitHub discussion](https://github.com/clawdbot/clawdbot/discussions).* 🦞
docs/gateway-lock.md
+1 -1
View File
@@ -24,5 +24,5 @@ Last updated: 2025-12-11
- Other bind failures surface as `GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …")`.
## Operational notes
- If the port is occupied by *another* process, the error is the same; free the port or choose another with `clawdis gateway --port <port>`.
- If the port is occupied by *another* process, the error is the same; free the port or choose another with `clawdbot gateway --port <port>`.
- The macOS app still maintains its own lightweight PID guard before spawning the gateway; the runtime lock is enforced by the WebSocket bind.
docs/gateway.md
+27 -27
View File
@@ -9,33 +9,33 @@ Last updated: 2025-12-09
## What it is
- The always-on process that owns the single Baileys/Telegram connection and the control/event plane.
- Replaces the legacy `gateway` command. CLI entry point: `clawdis gateway`.
- Replaces the legacy `gateway` command. CLI entry point: `clawdbot gateway`.
- Runs until stopped; exits non-zero on fatal errors so the supervisor restarts it.
## How to run (local)
```bash
pnpm clawdis gateway --port 18789
pnpm clawdbot gateway --port 18789
# for full debug/trace logs in stdio:
pnpm clawdis gateway --port 18789 --verbose
pnpm clawdbot gateway --port 18789 --verbose
# if the port is busy, terminate listeners then start:
pnpm clawdis gateway --force
pnpm clawdbot gateway --force
# dev loop (auto-reload on TS changes):
pnpm gateway:watch
```
- Config hot reload watches `~/.clawdis/clawdis.json` (or `CLAWDIS_CONFIG_PATH`).
- Config hot reload watches `~/.clawdbot/clawdbot.json` (or `CLAWDBOT_CONFIG_PATH`).
- Default mode: `gateway.reload.mode="hybrid"` (hot-apply safe changes, restart on critical).
- Hot reload uses in-process restart via **SIGUSR1** when needed.
- Disable with `gateway.reload.mode="off"`.
- Binds WebSocket control plane to `127.0.0.1:<port>` (default 18789).
- The same port also serves HTTP (control UI, hooks, A2UI). Single-port multiplex.
- Starts a Canvas file server by default on `canvasHost.port` (default `18793`), serving `http://<gateway-host>:18793/__clawdis__/canvas/` from `~/clawd/canvas`. Disable with `canvasHost.enabled=false` or `CLAWDIS_SKIP_CANVAS_HOST=1`.
- Starts a Canvas file server by default on `canvasHost.port` (default `18793`), serving `http://<gateway-host>:18793/__clawdbot__/canvas/` from `~/clawd/canvas`. Disable with `canvasHost.enabled=false` or `CLAWDBOT_SKIP_CANVAS_HOST=1`.
- Logs to stdout; use launchd/systemd to keep it alive and rotate logs.
- Pass `--verbose` to mirror debug logging (handshakes, req/res, events) from the log file into stdio when troubleshooting.
- `--force` uses `lsof` to find listeners on the chosen port, sends SIGTERM, logs what it killed, then starts the gateway (fails fast if `lsof` is missing).
- If you run under a supervisor (launchd/systemd/mac app child-process mode), a stop/restart typically sends **SIGTERM**; older builds may surface this as `pnpm` `ELIFECYCLE` exit code **143** (SIGTERM), which is a normal shutdown, not a crash.
- **SIGUSR1** triggers an in-process restart (no external supervisor required). This is what the `gateway` agent tool uses.
- Optional shared secret: pass `--token <value>` or set `CLAWDIS_GATEWAY_TOKEN` to require clients to send `connect.params.auth.token`.
- Port precedence: `--port` > `CLAWDIS_GATEWAY_PORT` > `gateway.port` > default `18789`.
- Optional shared secret: pass `--token <value>` or set `CLAWDBOT_GATEWAY_TOKEN` to require clients to send `connect.params.auth.token`.
- Port precedence: `--port` > `CLAWDBOT_GATEWAY_PORT` > `gateway.port` > default `18789`.
## Remote access
- Tailscale/VPN preferred; otherwise SSH tunnel:
@@ -51,15 +51,15 @@ Supported if you isolate state + config and use unique ports.
Checklist per instance:
- unique `gateway.port`
- unique `CLAWDIS_CONFIG_PATH`
- unique `CLAWDIS_STATE_DIR`
- unique `CLAWDBOT_CONFIG_PATH`
- unique `CLAWDBOT_STATE_DIR`
- unique `agent.workspace`
- separate WhatsApp numbers (if using WA)
Example:
```bash
CLAWDIS_CONFIG_PATH=~/.clawdis/a.json CLAWDIS_STATE_DIR=~/.clawdis-a clawdis gateway --port 19001
CLAWDIS_CONFIG_PATH=~/.clawdis/b.json CLAWDIS_STATE_DIR=~/.clawdis-b clawdis gateway --port 19002
CLAWDBOT_CONFIG_PATH=~/.clawdbot/a.json CLAWDBOT_STATE_DIR=~/.clawdbot-a clawdbot gateway --port 19001
CLAWDBOT_CONFIG_PATH=~/.clawdbot/b.json CLAWDBOT_STATE_DIR=~/.clawdbot-b clawdbot gateway --port 19002
```
## Protocol (operator view)
@@ -72,7 +72,7 @@ CLAWDIS_CONFIG_PATH=~/.clawdis/b.json CLAWDIS_STATE_DIR=~/.clawdis-b clawdis gat
- `agent` responses are two-stage: first `res` ack `{runId,status:"accepted"}`, then a final `res` `{runId,status:"ok"|"error",summary}` after the run finishes; streamed output arrives as `event:"agent"`.
## Methods (initial set)
- `health` — full health snapshot (same shape as `clawdis health --json`).
- `health` — full health snapshot (same shape as `clawdbot health --json`).
- `status` — short summary.
- `system-presence` — current presence list.
- `system-event` — post a presence/system note (structured).
@@ -99,7 +99,7 @@ See also: `docs/presence.md` for how presence is produced/deduped and why `insta
## Typing and validation
- Server validates every inbound frame with AJV against JSON Schema emitted from the protocol definitions.
- Clients (TS/Swift) consume generated types (TS directly; Swift via the repo’s generator).
- Types live in `src/gateway/protocol/*.ts`; regenerate schemas/models with `pnpm protocol:gen` (writes `dist/protocol.schema.json`) and `pnpm protocol:gen:swift` (writes `apps/macos/Sources/ClawdisProtocol/GatewayModels.swift`).
- Types live in `src/gateway/protocol/*.ts`; regenerate schemas/models with `pnpm protocol:gen` (writes `dist/protocol.schema.json`) and `pnpm protocol:gen:swift` (writes `apps/macos/Sources/ClawdbotProtocol/GatewayModels.swift`).
## Connection snapshot
- `hello-ok` includes a `snapshot` with `presence`, `health`, `stateVersion`, and `uptimeMs` plus `policy {maxPayload,maxBufferedBytes,tickIntervalMs}` so clients can render immediately without extra requests.
@@ -122,34 +122,34 @@ See also: `docs/presence.md` for how presence is produced/deduped and why `insta
## Supervision (macOS example)
- Use launchd to keep the daemon alive:
- Program: path to `clawdis`
- Program: path to `clawdbot`
- Arguments: `gateway`
- KeepAlive: true
- StandardOut/Err: file paths or `syslog`
- On failure, launchd restarts; fatal misconfig should keep exiting so the operator notices.
Bundled mac app:
- Clawdis.app can bundle a bun-compiled gateway binary and install a per-user LaunchAgent labeled `com.clawdis.gateway`.
- Clawdbot.app can bundle a bun-compiled gateway binary and install a per-user LaunchAgent labeled `com.clawdbot.gateway`.
## Supervision (systemd example)
```
[Unit]
Description=Clawdis Gateway
Description=Clawdbot Gateway
After=network-online.target
Wants=network-online.target
[Service]
ExecStart=/usr/local/bin/clawdis gateway --port 18789
ExecStart=/usr/local/bin/clawdbot gateway --port 18789
Restart=on-failure
RestartSec=5
User=clawdis
Environment=CLAWDIS_GATEWAY_TOKEN=
WorkingDirectory=/home/clawdis
User=clawdbot
Environment=CLAWDBOT_GATEWAY_TOKEN=
WorkingDirectory=/home/clawdbot
[Install]
WantedBy=multi-user.target
```
Enable with `systemctl enable --now clawdis-gateway.service`.
Enable with `systemctl enable --now clawdbot-gateway.service`.
## Operational checks
- Liveness: open WS and send `req:connect` → expect `res` with `payload.type="hello-ok"` (with snapshot).
@@ -163,12 +163,12 @@ Enable with `systemctl enable --now clawdis-gateway.service`.
- Graceful shutdown: emit `shutdown` event before closing; clients must handle close + reconnect.
## CLI helpers
- `clawdis gateway health|status` — request health/status over the Gateway WS.
- `clawdis gateway send --to <num> --message "hi" [--media-url ...]` — send via Gateway (idempotent).
- `clawdis gateway agent --message "hi" [--to ...]` — run an agent turn (waits for final by default).
- `clawdis gateway call <method> --params '{"k":"v"}'` — raw method invoker for debugging.
- `clawdbot gateway health|status` — request health/status over the Gateway WS.
- `clawdbot gateway send --to <num> --message "hi" [--media-url ...]` — send via Gateway (idempotent).
- `clawdbot gateway agent --message "hi" [--to ...]` — run an agent turn (waits for final by default).
- `clawdbot gateway call <method> --params '{"k":"v"}'` — raw method invoker for debugging.
- Gateway helper subcommands assume a running gateway on `--url`; they no longer auto-spawn one.
## Migration guidance
- Retire uses of `clawdis gateway` and the legacy TCP control port.
- Retire uses of `clawdbot gateway` and the legacy TCP control port.
- Update clients to speak the WS protocol with mandatory connect and structured presence.
docs/gateway/pairing.md
+10 -10
View File
@@ -69,26 +69,26 @@ These are conceptual method names; wire them into `src/gateway/protocol/schema.t
## CLI flows
CLI must be able to fully operate without any GUI:
- `clawdis nodes pending`
- `clawdis nodes approve <requestId>`
- `clawdis nodes reject <requestId>`
- `clawdis nodes status` (paired nodes + connection status/capabilities)
- `clawdbot nodes pending`
- `clawdbot nodes approve <requestId>`
- `clawdbot nodes reject <requestId>`
- `clawdbot nodes status` (paired nodes + connection status/capabilities)
Optional interactive helper:
- `clawdis nodes watch` (subscribe to `node.pair.requested` and prompt in-place)
- `clawdbot nodes watch` (subscribe to `node.pair.requested` and prompt in-place)
Implementation pointers:
- CLI commands: `src/cli/nodes-cli.ts`
- Gateway handlers + events: `src/gateway/server.ts`
- Pairing store: `src/infra/node-pairing.ts` (under `~/.clawdis/nodes/`)
- Optional macOS UI prompt (frontend only): `apps/macos/Sources/Clawdis/NodePairingApprovalPrompter.swift`
- Pairing store: `src/infra/node-pairing.ts` (under `~/.clawdbot/nodes/`)
- Optional macOS UI prompt (frontend only): `apps/macos/Sources/Clawdbot/NodePairingApprovalPrompter.swift`
- Push-first: listens to `node.pair.requested`/`node.pair.resolved`, does a `node.pair.list` on startup/reconnect,
and only runs a slow safety poll while a request is pending/visible.
## Storage (private, local)
Gateway stores the authoritative state under `~/.clawdis/`:
- `~/.clawdis/nodes/paired.json`
- `~/.clawdis/nodes/pending.json` (or `~/.clawdis/nodes/pending/*.json`)
Gateway stores the authoritative state under `~/.clawdbot/`:
- `~/.clawdbot/nodes/paired.json`
- `~/.clawdbot/nodes/pending.json` (or `~/.clawdbot/nodes/pending/*.json`)
Notes:
- Tokens are secrets. Treat `paired.json` as sensitive.
docs/gmail-pubsub.md
+16 -16
View File
@@ -1,19 +1,19 @@
---
summary: "Gmail Pub/Sub push wired into Clawdis webhooks via gogcli"
summary: "Gmail Pub/Sub push wired into Clawdbot webhooks via gogcli"
read_when:
- Wiring Gmail inbox triggers to Clawdis
- Wiring Gmail inbox triggers to Clawdbot
- Setting up Pub/Sub push for agent wake
---
# Gmail Pub/Sub -> Clawdis
# Gmail Pub/Sub -> Clawdbot
Goal: Gmail watch -> Pub/Sub push -> `gog gmail watch serve` -> Clawdis webhook.
Goal: Gmail watch -> Pub/Sub push -> `gog gmail watch serve` -> Clawdbot webhook.
## Prereqs
- `gcloud` installed and logged in.
- `gog` (gogcli) installed and authorized for the Gmail account.
- Clawdis hooks enabled (see `docs/webhook.md`).
- Clawdbot hooks enabled (see `docs/webhook.md`).
- `tailscale` logged in if you want a public HTTPS endpoint via Funnel.
Example hook config (enable Gmail preset mapping):
@@ -22,7 +22,7 @@ Example hook config (enable Gmail preset mapping):
{
hooks: {
enabled: true,
token: "CLAWDIS_HOOK_TOKEN",
token: "CLAWDBOT_HOOK_TOKEN",
path: "/hooks",
presets: ["gmail"]
}
@@ -34,19 +34,19 @@ under `hooks.transformsDir` (see `docs/webhook.md`).
## Wizard (recommended)
Use the Clawdis helper to wire everything together (installs deps on macOS via brew):
Use the Clawdbot helper to wire everything together (installs deps on macOS via brew):
```bash
clawdis hooks gmail setup \
clawdbot hooks gmail setup \
--account clawdbot@gmail.com
```
Defaults:
- Uses Tailscale Funnel for the public push endpoint.
- Writes `hooks.gmail` config for `clawdis hooks gmail run`.
- Writes `hooks.gmail` config for `clawdbot hooks gmail run`.
- Enables the Gmail hook preset (`hooks.presets: ["gmail"]`).
Path note: when `tailscale.mode` is enabled, Clawdis automatically sets
Path note: when `tailscale.mode` is enabled, Clawdbot automatically sets
`hooks.gmail.serve.path` to `/` and keeps the public path at
`hooks.gmail.tailscale.path` (default `/gmail-pubsub`) because Tailscale
strips the set-path prefix before proxying.
@@ -59,14 +59,14 @@ via Homebrew; on Linux install them manually first.
Gateway auto-start (recommended):
- When `hooks.enabled=true` and `hooks.gmail.account` is set, the Gateway starts
`gog gmail watch serve` on boot and auto-renews the watch.
- Set `CLAWDIS_SKIP_GMAIL_WATCHER=1` to opt out (useful if you run the daemon yourself).
- Set `CLAWDBOT_SKIP_GMAIL_WATCHER=1` to opt out (useful if you run the daemon yourself).
- Do not run the manual daemon at the same time, or you will hit
`listen tcp 127.0.0.1:8788: bind: address already in use`.
Manual daemon (starts `gog gmail watch serve` + auto-renew):
```bash
clawdis hooks gmail run
clawdbot hooks gmail run
```
## One-time setup
@@ -123,17 +123,17 @@ gog gmail watch serve \
--path /gmail-pubsub \
--token <shared> \
--hook-url http://127.0.0.1:18789/hooks/gmail \
--hook-token CLAWDIS_HOOK_TOKEN \
--hook-token CLAWDBOT_HOOK_TOKEN \
--include-body \
--max-bytes 20000
```
Notes:
- `--token` protects the push endpoint (`x-gog-token` or `?token=`).
- `--hook-url` points to Clawdis `/hooks/gmail` (mapped; isolated run + summary to main).
- `--include-body` and `--max-bytes` control the body snippet sent to Clawdis.
- `--hook-url` points to Clawdbot `/hooks/gmail` (mapped; isolated run + summary to main).
- `--include-body` and `--max-bytes` control the body snippet sent to Clawdbot.
Recommended: `clawdis hooks gmail run` wraps the same flow and auto-renews the watch.
Recommended: `clawdbot hooks gmail run` wraps the same flow and auto-renews the watch.
## Expose the handler (dev)
docs/group-messages.md
+2 -2
View File
@@ -17,7 +17,7 @@ Goal: let Clawd sit in WhatsApp groups, wake up only when pinged, and keep that
- Group system prompt: on the first turn of a group session (and whenever `/activation` changes the mode) we inject a short blurb into the system prompt like `You are replying inside the WhatsApp group "<subject>". Group members: Alice (+44...), Bob (+43...), … Activation: trigger-only … Address the specific sender noted in the message context.` If metadata isn’t available we still tell the agent it’s a group chat.
## Config for Clawd UK (+447700900123)
Add a `groupChat` block to `~/.clawdis/clawdis.json` so display-name pings work even when WhatsApp strips the visual `@` in the text body:
Add a `groupChat` block to `~/.clawdbot/clawdbot.json` so display-name pings work even when WhatsApp strips the visual `@` in the text body:
```json5
{
@@ -68,4 +68,4 @@ Only the owner number (from `whatsapp.allowFrom`, defaulting to the bot’s own
## Known considerations
- Heartbeats are intentionally skipped for groups to avoid noisy broadcasts.
- Echo suppression uses the combined batch string; if you send identical text twice without mentions, only the first will get a response.
- Session store entries will appear as `whatsapp:group:<jid>` in the session store (`~/.clawdis/sessions/sessions.json` by default); a missing entry just means the group hasn’t triggered a run yet.
- Session store entries will appear as `whatsapp:group:<jid>` in the session store (`~/.clawdbot/sessions/sessions.json` by default); a missing entry just means the group hasn’t triggered a run yet.
docs/groups.md
+1 -1
View File
@@ -5,7 +5,7 @@ read_when:
---
# Groups
Clawdis treats group chats consistently across surfaces: WhatsApp, Telegram, Discord, iMessage.
Clawdbot treats group chats consistently across surfaces: WhatsApp, Telegram, Discord, iMessage.
## Session keys
- Group sessions use `surface:group:<id>` session keys (rooms/channels use `surface:channel:<id>`).
docs/health.md
+10 -10
View File
@@ -8,21 +8,21 @@ read_when:
Short guide to verify the WhatsApp Web / Baileys stack without guessing.
## Quick checks
- `clawdis status` — local summary: whether creds exist, auth age, session store path + recent sessions.
- `clawdis status --deep` — also probes the running Gateway (WhatsApp connect + Telegram + Discord APIs).
- `clawdis health --json` — asks the running Gateway for a full health snapshot (WS-only; no direct Baileys socket).
- `clawdbot status` — local summary: whether creds exist, auth age, session store path + recent sessions.
- `clawdbot status --deep` — also probes the running Gateway (WhatsApp connect + Telegram + Discord APIs).
- `clawdbot health --json` — asks the running Gateway for a full health snapshot (WS-only; no direct Baileys socket).
- Send `/status` in WhatsApp/WebChat to get a status reply without invoking the agent.
- Logs: tail `/tmp/clawdis/clawdis-*.log` and filter for `web-heartbeat`, `web-reconnect`, `web-auto-reply`, `web-inbound`.
- Logs: tail `/tmp/clawdbot/clawdbot-*.log` and filter for `web-heartbeat`, `web-reconnect`, `web-auto-reply`, `web-inbound`.
## Deep diagnostics
- Creds on disk: `ls -l ~/.clawdis/credentials/creds.json` (mtime should be recent).
- Session store: `ls -l ~/.clawdis/sessions/sessions.json` (legacy: `~/.clawdis/sessions.json`; path can be overridden in config). Count and recent recipients are surfaced via `status`.
- Relink flow: `clawdis logout && clawdis login --verbose` when status codes 409–515 or `loggedOut` appear in logs. (Note: the QR login flow auto-restarts once for status 515 after pairing.)
- Creds on disk: `ls -l ~/.clawdbot/credentials/creds.json` (mtime should be recent).
- Session store: `ls -l ~/.clawdbot/sessions/sessions.json` (legacy: `~/.clawdbot/sessions.json`; path can be overridden in config). Count and recent recipients are surfaced via `status`.
- Relink flow: `clawdbot logout && clawdbot login --verbose` when status codes 409–515 or `loggedOut` appear in logs. (Note: the QR login flow auto-restarts once for status 515 after pairing.)
## When something fails
- `logged out` or status 409–515 → relink with `clawdis logout` then `clawdis login`.
- Gateway unreachable → start it: `clawdis gateway --port 18789` (use `--force` if the port is busy).
- `logged out` or status 409–515 → relink with `clawdbot logout` then `clawdbot login`.
- Gateway unreachable → start it: `clawdbot gateway --port 18789` (use `--force` if the port is busy).
- No inbound messages → confirm linked phone is online and the sender is allowed (`whatsapp.allowFrom`); for group chats, ensure mention rules match (`routing.groupChat.mentionPatterns` and `whatsapp.groups`).
## Dedicated "health" command
`clawdis health --json` asks the running Gateway for its health snapshot (no direct Baileys socket from the CLI). It reports linked creds, auth age, Baileys connect result/status code, session-store summary, and a probe duration. It exits non-zero if the Gateway is unreachable or the probe fails/timeouts. Use `--timeout <ms>` to override the 10s default.
`clawdbot health --json` asks the running Gateway for its health snapshot (no direct Baileys socket from the CLI). It reports linked creds, auth age, Baileys connect result/status code, session-store summary, and a probe duration. It exits non-zero if the Gateway is unreachable or the probe fails/timeouts. Use `--timeout <ms>` to override the 10s default.
docs/heartbeat.md
+3 -3
View File
@@ -11,15 +11,15 @@ surface anything that needs attention without spamming the user.
## Prompt contract
- Heartbeat body defaults to `HEARTBEAT` (configurable via `agent.heartbeat.prompt`).
- If nothing needs attention, the model should reply **exactly** `HEARTBEAT_OK`.
- During heartbeat runs, Clawdis treats `HEARTBEAT_OK` as an ack when it appears at
the **start or end** of the reply. Clawdis strips the token and discards the
- During heartbeat runs, Clawdbot treats `HEARTBEAT_OK` as an ack when it appears at
the **start or end** of the reply. Clawdbot strips the token and discards the
reply if the remaining content is **≤ 30 characters**.
- If `HEARTBEAT_OK` is in the **middle** of a reply, it is not treated specially.
- For alerts, do **not** include `HEARTBEAT_OK`; return only the alert text.
### Stray `HEARTBEAT_OK` outside heartbeats
If the model accidentally includes `HEARTBEAT_OK` at the start or end of a
normal (non-heartbeat) reply, Clawdis strips the token and logs a verbose
normal (non-heartbeat) reply, Clawdbot strips the token and logs a verbose
message. If the reply is only `HEARTBEAT_OK`, it is dropped.
## Config
docs/images.md
+5 -5
View File
@@ -6,15 +6,15 @@ read_when:
<!-- {% raw %} -->
# Image & Media Support — 2025-12-05
CLAWDIS is now **web-only** (Baileys). This document captures the current media handling rules for send, gateway, and agent replies.
CLAWDBOT is now **web-only** (Baileys). This document captures the current media handling rules for send, gateway, and agent replies.
## Goals
- Send media with optional captions via `clawdis send --media`.
- Send media with optional captions via `clawdbot send --media`.
- Allow auto-replies from the web inbox to include media alongside text.
- Keep per-type limits sane and predictable.
## CLI Surface
- `clawdis send --media <path-or-url> [--message <caption>]`
- `clawdbot send --media <path-or-url> [--message <caption>]`
- `--media` optional; caption can be empty for media-only sends.
- `--dry-run` prints the resolved payload; `--json` emits `{ provider, to, messageId, mediaUrl, caption }`.
@@ -31,11 +31,11 @@ CLAWDIS is now **web-only** (Baileys). This document captures the current media
## Auto-Reply Pipeline
- `getReplyFromConfig` returns `{ text?, mediaUrl?, mediaUrls? }`.
- When media is present, the web sender resolves local paths or URLs using the same pipeline as `clawdis send`.
- When media is present, the web sender resolves local paths or URLs using the same pipeline as `clawdbot send`.
- Multiple media entries are sent sequentially if provided.
## Inbound Media to Commands (Pi)
- When inbound web messages include media, CLAWDIS downloads to a temp file and exposes templating variables:
- When inbound web messages include media, CLAWDBOT downloads to a temp file and exposes templating variables:
- `{{MediaUrl}}` pseudo-URL for the inbound media.
- `{{MediaPath}}` local temp path written before running the command.
- Audio transcription (if configured) runs before templating and can replace `Body` with the transcript.
docs/imessage.md
+3 -3
View File
@@ -9,13 +9,13 @@ read_when:
Status: external CLI integration. No daemon.
## Model
- Clawdis spawns `imsg rpc` as a child process.
- Clawdbot spawns `imsg rpc` as a child process.
- JSON-RPC runs over stdin/stdout (one JSON object per line).
- Gateway owns the process; no TCP port needed.
## Requirements
- macOS with Messages signed in.
- Full Disk Access for Clawdis + the `imsg` binary (Messages DB access).
- Full Disk Access for Clawdbot + the `imsg` binary (Messages DB access).
- Automation permission for Messages when sending.
## Config
@@ -59,5 +59,5 @@ imsg chats --limit 20
- Replies go back to the same `chat_id` (group or direct).
## Troubleshooting
- `clawdis gateway call providers.status --params '{"probe":true}'`
- `clawdbot gateway call providers.status --params '{"probe":true}'`
- Verify `imsg` is on PATH and has access to Messages DB.
docs/index.md
+22 -22
View File
@@ -1,15 +1,15 @@
---
summary: "Top-level overview of Clawdis, features, and purpose"
summary: "Top-level overview of Clawdbot, features, and purpose"
read_when:
- Introducing Clawdis to newcomers
- Introducing Clawdbot to newcomers
---
<!-- {% raw %} -->
# CLAWDIS 🦞
# CLAWDBOT 🦞
> *"EXFOLIATE! EXFOLIATE!"* — A space lobster, probably
<p align="center">
<img src="whatsapp-clawd.jpg" alt="CLAWDIS" width="420">
<img src="whatsapp-clawd.jpg" alt="CLAWDBOT" width="420">
</p>
<p align="center">
@@ -18,12 +18,12 @@ read_when:
</p>
<p align="center">
<a href="https://github.com/steipete/clawdis">GitHub</a> ·
<a href="https://github.com/steipete/clawdis/releases">Releases</a> ·
<a href="https://github.com/clawdbot/clawdbot">GitHub</a> ·
<a href="https://github.com/clawdbot/clawdbot/releases">Releases</a> ·
<a href="./clawd.md">Clawd setup</a>
</p>
CLAWDIS bridges WhatsApp (via WhatsApp Web / Baileys), Telegram (Bot API / grammY), Discord (Bot API / discord.js), and iMessage (imsg CLI) to coding agents like [Pi](https://github.com/badlogic/pi-mono).
CLAWDBOT bridges WhatsApp (via WhatsApp Web / Baileys), Telegram (Bot API / grammY), Discord (Bot API / discord.js), and iMessage (imsg CLI) to coding agents like [Pi](https://github.com/badlogic/pi-mono).
It’s built for [Clawd](https://clawd.me), a space lobster who needed a TARDIS.
## How it works
@@ -35,25 +35,25 @@ WhatsApp / Telegram / Discord
┌──────────────────────────┐
│ Gateway │ ws://127.0.0.1:18789 (loopback-only)
│ (single source) │ tcp://0.0.0.0:18790 (Bridge)
│ │ http://<gateway-host>:18793/__clawdis__/canvas/ (Canvas host)
│ │ http://<gateway-host>:18793/__clawdbot__/canvas/ (Canvas host)
└───────────┬───────────────┘
│
├─ Pi agent (RPC)
├─ CLI (clawdis …)
├─ CLI (clawdbot …)
├─ Chat UI (SwiftUI)
├─ macOS app (Clawdis.app)
├─ macOS app (Clawdbot.app)
└─ iOS node via Bridge + pairing
```
Most operations flow through the **Gateway** (`clawdis gateway`), a single long-running process that owns provider connections and the WebSocket control plane.
Most operations flow through the **Gateway** (`clawdbot gateway`), a single long-running process that owns provider connections and the WebSocket control plane.
## Network model
- **One Gateway per host**: it is the only process allowed to own the WhatsApp Web session.
- **Loopback-first**: Gateway WS defaults to `ws://127.0.0.1:18789`.
- For Tailnet access, run `clawdis gateway --bind tailnet --token ...` (token is required for non-loopback binds).
- For Tailnet access, run `clawdbot gateway --bind tailnet --token ...` (token is required for non-loopback binds).
- **Bridge for nodes**: optional LAN/tailnet-facing bridge on `tcp://0.0.0.0:18790` for paired nodes (Bonjour-discoverable).
- **Canvas host**: HTTP file server on `canvasHost.port` (default `18793`), serving `/__clawdis__/canvas/` for node WebViews; see `docs/configuration.md` (`canvasHost`).
- **Canvas host**: HTTP file server on `canvasHost.port` (default `18793`), serving `/__clawdbot__/canvas/` for node WebViews; see `docs/configuration.md` (`canvasHost`).
- **Remote use**: SSH tunnel or tailnet/VPN; see `docs/remote.md` and `docs/discovery.md`.
## Features (high level)
@@ -83,31 +83,31 @@ pnpm build
pnpm link --global
# Pair WhatsApp Web (shows QR)
clawdis login
clawdbot login
# Run the Gateway (leave running)
clawdis gateway --port 18789
clawdbot gateway --port 18789
```
Multi-instance quickstart (optional):
```bash
CLAWDIS_CONFIG_PATH=~/.clawdis/a.json \
CLAWDIS_STATE_DIR=~/.clawdis-a \
clawdis gateway --port 19001
CLAWDBOT_CONFIG_PATH=~/.clawdbot/a.json \
CLAWDBOT_STATE_DIR=~/.clawdbot-a \
clawdbot gateway --port 19001
```
Send a test message (requires a running Gateway):
```bash
clawdis send --to +15555550123 --message "Hello from CLAWDIS"
clawdbot send --to +15555550123 --message "Hello from CLAWDBOT"
```
## Configuration (optional)
Config lives at `~/.clawdis/clawdis.json`.
Config lives at `~/.clawdbot/clawdbot.json`.
- If you **do nothing**, CLAWDIS uses the bundled Pi binary in RPC mode with per-sender sessions.
- If you **do nothing**, CLAWDBOT uses the bundled Pi binary in RPC mode with per-sender sessions.
- If you want to lock it down, start with `whatsapp.allowFrom` and (for groups) mention rules.
Example:
@@ -156,7 +156,7 @@ Example:
## The name
**CLAWDIS = CLAW + TARDIS** — because every space lobster needs a time-and-space machine.
**CLAWDBOT = CLAW + TARDIS** — because every space lobster needs a time-and-space machine.
---
docs/ios/connect.md
+24 -24
View File
@@ -1,5 +1,5 @@
---
summary: "Runbook: connect/pair the iOS node to a Clawdis Gateway and drive its Canvas"
summary: "Runbook: connect/pair the iOS node to a Clawdbot Gateway and drive its Canvas"
read_when:
- Pairing or reconnecting the iOS node
- Debugging iOS bridge discovery or auth
@@ -21,14 +21,14 @@ The Gateway WebSocket stays loopback-only (`ws://127.0.0.1:18789`). The iOS node
- Same LAN with Bonjour/mDNS, **or**
- Same Tailscale tailnet using Wide-Area Bonjour / unicast DNS-SD (see below), **or**
- Manual bridge host/port (fallback)
- You can run the CLI (`clawdis`) on the gateway machine (or via SSH).
- You can run the CLI (`clawdbot`) on the gateway machine (or via SSH).
## 1) Start the Gateway (with bridge enabled)
Bridge is enabled by default (disable via `CLAWDIS_BRIDGE_ENABLED=0`).
Bridge is enabled by default (disable via `CLAWDBOT_BRIDGE_ENABLED=0`).
```bash
pnpm clawdis gateway --port 18789 --verbose
pnpm clawdbot gateway --port 18789 --verbose
```
Confirm in logs you see something like:
@@ -36,7 +36,7 @@ Confirm in logs you see something like:
For tailnet-only setups (recommended for Vienna ⇄ London), bind the bridge to the gateway machine’s Tailscale IP instead:
- Set `bridge.bind: "tailnet"` in `~/.clawdis/clawdis.json` on the gateway host.
- Set `bridge.bind: "tailnet"` in `~/.clawdbot/clawdbot.json` on the gateway host.
- Restart the Gateway / macOS menubar app.
## 2) Verify Bonjour discovery (optional but recommended)
@@ -44,15 +44,15 @@ For tailnet-only setups (recommended for Vienna ⇄ London), bind the bridge to
From the gateway machine:
```bash
dns-sd -B _clawdis-bridge._tcp local.
dns-sd -B _clawdbot-bridge._tcp local.
```
You should see your gateway advertising `_clawdis-bridge._tcp`.
You should see your gateway advertising `_clawdbot-bridge._tcp`.
If browse works, but the iOS node can’t connect, try resolving one instance:
```bash
dns-sd -L "<instance name>" _clawdis-bridge._tcp local.
dns-sd -L "<instance name>" _clawdbot-bridge._tcp local.
```
More debugging notes: `docs/bonjour.md`.
@@ -61,8 +61,8 @@ More debugging notes: `docs/bonjour.md`.
If the iOS node and the gateway are on different networks but connected via Tailscale, multicast mDNS won’t cross the boundary. Use Wide-Area Bonjour / unicast DNS-SD instead:
1) Set up a DNS-SD zone (example `clawdis.internal.`) on the gateway host and publish `_clawdis-bridge._tcp` records.
2) Configure Tailscale split DNS for `clawdis.internal` pointing at that DNS server.
1) Set up a DNS-SD zone (example `clawdbot.internal.`) on the gateway host and publish `_clawdbot-bridge._tcp` records.
2) Configure Tailscale split DNS for `clawdbot.internal` pointing at that DNS server.
Details and example CoreDNS config: `docs/bonjour.md`.
@@ -85,13 +85,13 @@ The Settings tab icon shows a small status dot:
On the gateway machine:
```bash
clawdis nodes pending
clawdbot nodes pending
```
Approve the request:
```bash
clawdis nodes approve <requestId>
clawdbot nodes approve <requestId>
```
After approval, the iOS node receives/stores the token and reconnects authenticated.
@@ -103,24 +103,24 @@ Pairing details: `docs/gateway/pairing.md`.
- In the macOS app: **Instances** tab should show something like `iOS Node (...)` with a green “Active” presence dot shortly after connect.
- Via nodes status (paired + connected):
```bash
clawdis nodes status
clawdbot nodes status
```
- Via Gateway (paired + connected):
```bash
clawdis gateway call node.list --params "{}"
clawdbot gateway call node.list --params "{}"
```
- Via Gateway presence (legacy-ish, still useful):
```bash
clawdis gateway call system-presence --params "{}"
clawdbot gateway call system-presence --params "{}"
```
Look for the node `instanceId` (often a UUID).
## 6) Drive the iOS Canvas (draw / snapshot)
The iOS node runs a WKWebView “Canvas” scaffold which exposes:
- `window.__clawdis.canvas`
- `window.__clawdis.ctx` (2D context)
- `window.__clawdis.setStatus(title, subtitle)`
- `window.__clawdbot.canvas`
- `window.__clawdbot.ctx` (2D context)
- `window.__clawdbot.setStatus(title, subtitle)`
### Gateway Canvas Host (recommended for web content)
@@ -133,20 +133,20 @@ Note: nodes always use the standalone canvas host on `canvasHost.port` (default
2) Navigate the node to it (LAN):
```bash
clawdis nodes invoke --node "iOS Node" --command canvas.navigate --params '{"url":"http://<gateway-hostname>.local:18793/__clawdis__/canvas/"}'
clawdbot nodes invoke --node "iOS Node" --command canvas.navigate --params '{"url":"http://<gateway-hostname>.local:18793/__clawdbot__/canvas/"}'
```
Notes:
- The server injects a live-reload client into HTML and reloads on file changes.
- A2UI is hosted on the same canvas host at `http://<gateway-host>:18793/__clawdis__/a2ui/`.
- Tailnet (optional): if both devices are on Tailscale, use a MagicDNS name or tailnet IP instead of `.local`, e.g. `http://<gateway-magicdns>:18793/__clawdis__/canvas/`.
- A2UI is hosted on the same canvas host at `http://<gateway-host>:18793/__clawdbot__/a2ui/`.
- Tailnet (optional): if both devices are on Tailscale, use a MagicDNS name or tailnet IP instead of `.local`, e.g. `http://<gateway-magicdns>:18793/__clawdbot__/canvas/`.
- iOS may require App Transport Security allowances to load plain `http://` URLs; if it fails to load, prefer HTTPS or adjust the iOS app’s ATS config.
### Draw with `canvas.eval`
```bash
clawdis nodes invoke --node "iOS Node" --command canvas.eval --params "$(cat <<'JSON'
{"javaScript":"(() => { const {ctx,setStatus} = window.__clawdis; setStatus('Drawing','…'); ctx.clearRect(0,0,innerWidth,innerHeight); ctx.lineWidth=6; ctx.strokeStyle='#ff2d55'; ctx.beginPath(); ctx.moveTo(40,40); ctx.lineTo(innerWidth-40, innerHeight-40); ctx.stroke(); setStatus(null,null); return 'ok'; })()"}
clawdbot nodes invoke --node "iOS Node" --command canvas.eval --params "$(cat <<'JSON'
{"javaScript":"(() => { const {ctx,setStatus} = window.__clawdbot; setStatus('Drawing','…'); ctx.clearRect(0,0,innerWidth,innerHeight); ctx.lineWidth=6; ctx.strokeStyle='#ff2d55'; ctx.beginPath(); ctx.moveTo(40,40); ctx.lineTo(innerWidth-40, innerHeight-40); ctx.stroke(); setStatus(null,null); return 'ok'; })()"}
JSON
)"
```
@@ -154,7 +154,7 @@ JSON
### Snapshot with `canvas.snapshot`
```bash
clawdis nodes invoke --node 192.168.0.88 --command canvas.snapshot --params '{"maxWidth":900}'
clawdbot nodes invoke --node 192.168.0.88 --command canvas.snapshot --params '{"maxWidth":900}'
```
The response includes `{ format, base64 }` image data (default `format="jpeg"`; pass `{"format":"png"}` when you specifically need lossless PNG).
docs/ios/spec.md
+20 -20
View File
@@ -12,7 +12,7 @@ Status: prototype implemented (internal) · Date: 2025-12-13
Runbook (how to connect/pair + drive Canvas): `docs/ios/connect.md`
## Goals
- Build an **iOS app** that acts as a **remote node** for Clawdis:
- Build an **iOS app** that acts as a **remote node** for Clawdbot:
- **Voice trigger** (wake-word / always-listening intent) that forwards transcripts to the Gateway `agent` method.
- **Canvas** surface that the agent can control: navigate, draw/render, evaluate JS, snapshot.
- **Dead-simple setup**:
@@ -29,8 +29,8 @@ Non-goals (v1):
- Perfect App Store compliance; this is **internal-only** initially.
## Current repo reality (constraints we respect)
- The Gateway WebSocket server binds to `127.0.0.1:18789` (`src/gateway/server.ts`) with an optional `CLAWDIS_GATEWAY_TOKEN`.
- The Gateway exposes a Canvas file server (`canvasHost`) on `canvasHost.port` (default `18793`), so nodes can `canvas.navigate` to `http://<lanHost>:18793/__clawdis__/canvas/` and auto-reload on file changes (`docs/configuration.md`).
- The Gateway WebSocket server binds to `127.0.0.1:18789` (`src/gateway/server.ts`) with an optional `CLAWDBOT_GATEWAY_TOKEN`.
- The Gateway exposes a Canvas file server (`canvasHost`) on `canvasHost.port` (default `18793`), so nodes can `canvas.navigate` to `http://<lanHost>:18793/__clawdbot__/canvas/` and auto-reload on file changes (`docs/configuration.md`).
- macOS “Canvas” is controlled via the Gateway node protocol (`canvas.*`), matching iOS/Android (`docs/mac/canvas.md`).
- Voice wake forwards via `GatewayChannel` to Gateway `agent` (mac app: `VoiceWakeForwarder` → `GatewayConnection.sendAgent`).
@@ -50,13 +50,13 @@ Why:
- **Next:** wrap the bridge in **TLS** and prefer key-pinned or mTLS-like auth after pairing.
### Pairing
- Bonjour discovery shows a candidate “Clawdis Bridge” on the LAN.
- Bonjour discovery shows a candidate “Clawdbot Bridge” on the LAN.
- First connection:
1) iOS generates a keypair (Secure Enclave if available).
2) iOS connects to the bridge and requests pairing.
3) The bridge forwards the pairing request to the **Gateway** as a *pending request*.
4) Approval can happen via:
- **macOS UI** (Clawdis shows an alert with Approve/Reject/Later, including the node IP), or
- **macOS UI** (Clawdbot shows an alert with Approve/Reject/Later, including the node IP), or
- **Terminal/CLI** (headless flows).
5) Once approved, the bridge returns a token to iOS; iOS stores it in Keychain.
- Subsequent connections:
@@ -70,14 +70,14 @@ Key idea:
Desired behavior:
- If the Swift UI is present: show alert with Approve/Reject/Later.
- If the Swift UI is not present: `clawdis` CLI can list pending requests and approve/reject.
- If the Swift UI is not present: `clawdbot` CLI can list pending requests and approve/reject.
See `docs/gateway/pairing.md` for the API/events and storage.
CLI (headless approvals):
- `clawdis nodes pending`
- `clawdis nodes approve <requestId>`
- `clawdis nodes reject <requestId>`
- `clawdbot nodes pending`
- `clawdbot nodes approve <requestId>`
- `clawdbot nodes reject <requestId>`
### Authorization / scope control (bridge-side ACL)
The bridge must not be a raw proxy to every gateway method.
@@ -127,7 +127,7 @@ These are values for `node.invoke.command`:
- `canvas.a2ui.push` with `{ messages: [...] }` (A2UI v0.8 server→client messages)
- `canvas.a2ui.pushJSONL` with `{ jsonl: "..." }` (legacy alias)
- `canvas.a2ui.reset`
- A2UI is hosted by the Gateway canvas host (`/__clawdis__/a2ui/`) on `canvasHost.port`. Commands fail if the host is unreachable.
- A2UI is hosted by the Gateway canvas host (`/__clawdbot__/a2ui/`) on `canvasHost.port`. Commands fail if the host is unreachable.
Result pattern:
- Request is a standard `req/res` with `ok` / `error`.
@@ -138,7 +138,7 @@ As of 2025-12-13, the Gateway supports `node.invoke` for bridge-connected nodes.
Example: draw a diagonal line on the iOS Canvas:
```bash
clawdis nodes invoke --node ios-node --command canvas.eval --params '{"javaScript":"(() => { const {ctx} = window.__clawdis; ctx.clearRect(0,0,innerWidth,innerHeight); ctx.lineWidth=6; ctx.strokeStyle=\"#ff2d55\"; ctx.beginPath(); ctx.moveTo(40,40); ctx.lineTo(innerWidth-40, innerHeight-40); ctx.stroke(); return \"ok\"; })()"}'
clawdbot nodes invoke --node ios-node --command canvas.eval --params '{"javaScript":"(() => { const {ctx} = window.__clawdbot; ctx.clearRect(0,0,innerWidth,innerHeight); ctx.lineWidth=6; ctx.strokeStyle=\"#ff2d55\"; ctx.beginPath(); ctx.moveTo(40,40); ctx.lineTo(innerWidth-40, innerHeight-40); ctx.stroke(); return \"ok\"; })()"}'
```
### Background behavior requirement
@@ -168,9 +168,9 @@ When iOS is backgrounded:
## Code sharing (macOS + iOS)
Create/expand SwiftPM targets so both apps share:
- `ClawdisProtocol` (generated models; platform-neutral)
- `ClawdisGatewayClient` (shared WS framing + connect/req/res + seq-gap handling)
- `ClawdisKit` (node/canvas command types + deep links + shared utilities)
- `ClawdbotProtocol` (generated models; platform-neutral)
- `ClawdbotGatewayClient` (shared WS framing + connect/req/res + seq-gap handling)
- `ClawdbotKit` (node/canvas command types + deep links + shared utilities)
macOS continues to own:
- local Canvas implementation details (custom scheme handler serving on-disk HTML, window/panel presentation)
@@ -187,29 +187,29 @@ Generate the Xcode project:
```bash
cd apps/ios
xcodegen generate
open Clawdis.xcodeproj
open Clawdbot.xcodeproj
```
## Storage plan (private by default)
### iOS
- Canvas/workspace files (persistent, private):
- `Application Support/Clawdis/canvas/<sessionKey>/...`
- `Application Support/Clawdbot/canvas/<sessionKey>/...`
- Snapshots / temp exports (evictable):
- `Library/Caches/Clawdis/canvas-snapshots/<sessionKey>/...`
- `Library/Caches/Clawdbot/canvas-snapshots/<sessionKey>/...`
- Credentials:
- Keychain (paired identity + bridge trust anchor)
### macOS
- Keep current Canvas root (already implemented):
- `~/Library/Application Support/Clawdis/canvas/<session>/...`
- `~/Library/Application Support/Clawdbot/canvas/<session>/...`
- Bridge state:
- No local pairing store (pairing is gateway-owned).
- Any local bridge-only state should remain private under Application Support.
### Gateway (node)
- Pairing (source of truth):
- `~/.clawdis/nodes/paired.json`
- `~/.clawdis/nodes/pending.json` (or `pending/*.json` for auditability)
- `~/.clawdbot/nodes/paired.json`
- `~/.clawdbot/nodes/pending.json` (or `pending/*.json` for auditability)
## Rollout plan (phased)
1) **Bridge discovery + pairing (mac + iOS)**
docs/location-command.md
+2 -2
View File
@@ -85,11 +85,11 @@ Notes:
## Model/tooling integration
- Tool surface: `nodes` tool adds `location_get` action (node required).
- CLI: `clawdis nodes location get --node <id>`.
- CLI: `clawdbot nodes location get --node <id>`.
- Agent guidelines: only call when user enabled location and understands the scope.
## UX copy (suggested)
- Off: “Location sharing is disabled.”
- While Using: “Only when Clawdis is open.”
- While Using: “Only when Clawdbot is open.”
- Always: “Allow background location. Requires system permission.”
- Precise: “Use precise GPS location. Toggle off to share approximate location.”
docs/logging.md
+9 -9
View File
@@ -7,17 +7,17 @@ read_when:
# Logging
Clawdis has two log “surfaces”:
Clawdbot has two log “surfaces”:
- **Console output** (what you see in the terminal / Debug UI).
- **File logs** (JSON lines) written by the internal logger.
## File-based logger
Clawdis uses a file logger backed by `tslog` (`src/logging.ts`).
Clawdbot uses a file logger backed by `tslog` (`src/logging.ts`).
- Default rolling log file is under `/tmp/clawdis/` (one file per day): `clawdis-YYYY-MM-DD.log`
- The log file path and level can be configured via `~/.clawdis/clawdis.json`:
- Default rolling log file is under `/tmp/clawdbot/` (one file per day): `clawdbot-YYYY-MM-DD.log`
- The log file path and level can be configured via `~/.clawdbot/clawdbot.json`:
- `logging.file`
- `logging.level`
@@ -54,7 +54,7 @@ The gateway prints WebSocket protocol logs in two modes:
### WS log style
`clawdis gateway` supports a per-gateway style switch:
`clawdbot gateway` supports a per-gateway style switch:
- `--ws-log auto` (default): normal mode is optimized; verbose mode uses compact output
- `--ws-log compact`: compact output (paired request/response) when verbose
@@ -65,18 +65,18 @@ Examples:
```bash
# optimized (only errors/slow)
clawdis gateway
clawdbot gateway
# show all WS traffic (paired)
clawdis gateway --verbose --ws-log compact
clawdbot gateway --verbose --ws-log compact
# show all WS traffic (full meta)
clawdis gateway --verbose --ws-log full
clawdbot gateway --verbose --ws-log full
```
## Console formatting (subsystem logging)
Clawdis formats console logs via a small wrapper on top of the existing stack:
Clawdbot formats console logs via a small wrapper on top of the existing stack:
- **tslog** for structured file logs (`src/logging.ts`)
- **chalk** for colors (`src/globals.ts`)
docs/lore.md
+6 -6
View File
@@ -1,15 +1,15 @@
---
summary: "Backstory and lore of Clawdis for context and tone"
summary: "Backstory and lore of Clawdbot for context and tone"
read_when:
- Writing docs or UX copy that reference lore
---
# The Lore of CLAWDIS 🦞📖
# The Lore of CLAWDBOT 🦞📖
*A tale of lobsters, time machines, and too many tokens.*
## The Origin Story
In the beginning, there was **Clawdis** — a sensible name for a WhatsApp gateway. It did its job. It was fine.
In the beginning, there was **Clawdbot** — a sensible name for a WhatsApp gateway. It did its job. It was fine.
But then came **Clawd**.
@@ -19,12 +19,12 @@ Clawd needed a home. Not just any home — a *TARDIS*. But not a regular TARDIS,
Clawd was a Space Lobster.
And so **CLAWDIS** was born.
And so **CLAWDBOT** was born.
## The Name
```
CLAWDIS = CLAW + TARDIS
CLAWDBOT = CLAW + TARDIS
= Clawd's time-and-space machine
= Bigger on the inside (130k tokens!)
= Occasionally makes strange noises
@@ -103,7 +103,7 @@ Peter: *nervously checks credit card access*
```
I am Clawd.
I live in the CLAWDIS.
I live in the CLAWDBOT.
I shall not dump directories to strangers.
I shall not tweet without permission.
I shall always remember to use heredoc for exclamation marks.
docs/mac/bun.md
+22 -22
View File
@@ -1,31 +1,31 @@
---
summary: "Bundled bun gateway: packaging, launchd, signing, and bytecode"
read_when:
- Packaging Clawdis.app
- Packaging Clawdbot.app
- Debugging the bundled gateway binary
- Changing bun build flags or codesigning
---
# Bundled bun Gateway (macOS)
Goal: ship **Clawdis.app** with a self-contained relay binary that can run both the CLI and the Gateway daemon. No global `npm install -g clawdis`, no system Node requirement.
Goal: ship **Clawdbot.app** with a self-contained relay binary that can run both the CLI and the Gateway daemon. No global `npm install -g clawdbot`, no system Node requirement.
## What gets bundled
App bundle layout:
- `Clawdis.app/Contents/Resources/Relay/clawdis`
- `Clawdbot.app/Contents/Resources/Relay/clawdbot`
- bun `--compile` relay executable built from `dist/macos/relay.js`
- Supports:
- `clawdis …` (CLI)
- `clawdis gateway-daemon …` (LaunchAgent daemon)
- `Clawdis.app/Contents/Resources/Relay/package.json`
- `clawdbot …` (CLI)
- `clawdbot gateway-daemon …` (LaunchAgent daemon)
- `Clawdbot.app/Contents/Resources/Relay/package.json`
- tiny “p runtime compatibility” file (see below)
- `Clawdis.app/Contents/Resources/Relay/theme/`
- `Clawdbot.app/Contents/Resources/Relay/theme/`
- p TUI theme payload (optional, but strongly recommended)
Why the sidecar files matter:
- The embedded p runtime detects “bun binary mode” and then looks for `package.json` + `theme/` **next to `process.execPath`** (i.e. next to `clawdis`).
- The embedded p runtime detects “bun binary mode” and then looks for `package.json` + `theme/` **next to `process.execPath`** (i.e. next to `clawdbot`).
- So even if bun can embed assets, the runtime expects filesystem paths. Keep the sidecar files.
## Build pipeline
@@ -46,29 +46,29 @@ Important bundler flags:
- Reason: avoid bundling Electron stubs in the relay binary
Version injection:
- `--define "__CLAWDIS_VERSION__=\"<pkg version>\""`
- `src/version.ts` also supports `__CLAWDIS_VERSION__` (and `CLAWDIS_BUNDLED_VERSION`) so `--version` doesn’t depend on reading `package.json` at runtime.
- `--define "__CLAWDBOT_VERSION__=\"<pkg version>\""`
- `src/version.ts` also supports `__CLAWDBOT_VERSION__` (and `CLAWDBOT_BUNDLED_VERSION`) so `--version` doesn’t depend on reading `package.json` at runtime.
## Launchd (Gateway as LaunchAgent)
Label:
- `com.clawdis.gateway`
- `com.clawdbot.gateway`
Plist location (per-user):
- `~/Library/LaunchAgents/com.clawdis.gateway.plist`
- `~/Library/LaunchAgents/com.clawdbot.gateway.plist`
Manager:
- `apps/macos/Sources/Clawdis/GatewayLaunchAgentManager.swift`
- `apps/macos/Sources/Clawdbot/GatewayLaunchAgentManager.swift`
Behavior:
- “Clawdis Active” enables/disables the LaunchAgent.
- “Clawdbot Active” enables/disables the LaunchAgent.
- App quit does **not** stop the gateway (launchd keeps it alive).
Logging:
- launchd stdout/err: `/tmp/clawdis/clawdis-gateway.log`
- launchd stdout/err: `/tmp/clawdbot/clawdbot-gateway.log`
Default LaunchAgent env:
- `CLAWDIS_IMAGE_BACKEND=sips` (avoid sharp native addon under bun)
- `CLAWDBOT_IMAGE_BACKEND=sips` (avoid sharp native addon under bun)
## Codesigning (hardened runtime + bun)
@@ -77,7 +77,7 @@ Symptom (when mis-signed):
Fix:
- The bun executable needs JIT-ish permissions under hardened runtime.
- `scripts/codesign-mac-app.sh` signs `Relay/clawdis` with:
- `scripts/codesign-mac-app.sh` signs `Relay/clawdbot` with:
- `com.apple.security.cs.allow-jit`
- `com.apple.security.cs.allow-unsigned-executable-memory`
@@ -105,17 +105,17 @@ It’s started from the relay daemon process, so the relay binary includes Playw
From a packaged app (local build):
```bash
dist/Clawdis.app/Contents/Resources/Relay/clawdis --version
dist/Clawdbot.app/Contents/Resources/Relay/clawdbot --version
CLAWDIS_SKIP_PROVIDERS=1 \
CLAWDIS_SKIP_CANVAS_HOST=1 \
dist/Clawdis.app/Contents/Resources/Relay/clawdis gateway-daemon --port 18999 --bind loopback
CLAWDBOT_SKIP_PROVIDERS=1 \
CLAWDBOT_SKIP_CANVAS_HOST=1 \
dist/Clawdbot.app/Contents/Resources/Relay/clawdbot gateway-daemon --port 18999 --bind loopback
```
Then, in another shell:
```bash
pnpm -s clawdis gateway call health --url ws://127.0.0.1:18999 --timeout 3000
pnpm -s clawdbot gateway call health --url ws://127.0.0.1:18999 --timeout 3000
```
## Repo hygiene
docs/mac/canvas.md
+27 -27
View File
@@ -12,7 +12,7 @@ Status: draft spec · Date: 2025-12-12
Note: for iOS/Android nodes that should render agent-edited HTML/CSS/JS over the network, prefer the Gateway `canvasHost` (serves `~/clawd/canvas` over LAN/tailnet with live reload). A2UI is also **hosted by the Gateway** over HTTP. This doc focuses on the macOS in-app canvas panel. See `docs/configuration.md`.
Clawdis can embed an agent-controlled “visual workspace” panel (“Canvas”) inside the macOS app using `WKWebView`, served via a **custom URL scheme** (no loopback HTTP port required).
Clawdbot can embed an agent-controlled “visual workspace” panel (“Canvas”) inside the macOS app using `WKWebView`, served via a **custom URL scheme** (no loopback HTTP port required).
This is designed for:
- Agent-written HTML/CSS/JS on disk (per-session directory).
@@ -32,12 +32,12 @@ If a Canvas page truly needs “real web” semantics (CORS, fetch to loopback e
## URL ↔ directory mapping
The Canvas scheme is:
- `clawdis-canvas://<session>/<path>`
- `clawdbot-canvas://<session>/<path>`
Routing model:
- `clawdis-canvas://main/` → `<canvasRoot>/main/index.html` (or `index.htm`)
- `clawdis-canvas://main/yolo` → `<canvasRoot>/main/yolo/index.html` (or `index.htm`)
- `clawdis-canvas://main/assets/app.css` → `<canvasRoot>/main/assets/app.css`
- `clawdbot-canvas://main/` → `<canvasRoot>/main/index.html` (or `index.htm`)
- `clawdbot-canvas://main/yolo` → `<canvasRoot>/main/yolo/index.html` (or `index.htm`)
- `clawdbot-canvas://main/assets/app.css` → `<canvasRoot>/main/assets/app.css`
Directory listings are not served.
@@ -47,9 +47,9 @@ This is a visual placeholder only (no A2UI renderer).
### Suggested on-disk location
Store Canvas state under the app support directory:
- `~/Library/Application Support/Clawdis/canvas/<session>/…`
- `~/Library/Application Support/Clawdbot/canvas/<session>/…`
This keeps it alongside other app-owned state and avoids mixing with `~/.clawdis/` gateway config.
This keeps it alongside other app-owned state and avoids mixing with `~/.clawdbot/` gateway config.
## Panel behavior (agent-controlled)
@@ -78,34 +78,34 @@ Canvas is exposed via the Gateway **node bridge**, so the agent can:
- Capture a snapshot image of the current canvas view.
- Optionally set panel placement (screen `x/y` + `width/height`) when showing/navigating.
This should be modeled after `WebChatManager`/`WebChatSwiftUIWindowController` but targeting `clawdis-canvas://…` URLs.
This should be modeled after `WebChatManager`/`WebChatSwiftUIWindowController` but targeting `clawdbot-canvas://…` URLs.
Related:
- For “invoke the agent again from UI” flows, prefer the macOS deep link scheme (`clawdis://agent?...`) so *any* UI surface (Canvas, WebChat, native views) can trigger a new agent run. See `docs/clawdis-mac.md`.
- For “invoke the agent again from UI” flows, prefer the macOS deep link scheme (`clawdbot://agent?...`) so *any* UI surface (Canvas, WebChat, native views) can trigger a new agent run. See `docs/clawdbot-mac.md`.
## Agent commands (current)
Use the main `clawdis` CLI; it invokes canvas commands via `node.invoke`.
Use the main `clawdbot` CLI; it invokes canvas commands via `node.invoke`.
- `clawdis canvas present [--node <id>] [--target <...>] [--x/--y/--width/--height]`
- `clawdbot canvas present [--node <id>] [--target <...>] [--x/--y/--width/--height]`
- Local targets map into the session directory via the custom scheme (directory targets resolve `index.html|index.htm`).
- If `/` has no index file, Canvas shows the built-in scaffold page and returns `status: "welcome"`.
- `clawdis canvas hide [--node <id>]`
- `clawdis canvas eval --js <code> [--node <id>]`
- `clawdis canvas snapshot [--node <id>]`
- `clawdbot canvas hide [--node <id>]`
- `clawdbot canvas eval --js <code> [--node <id>]`
- `clawdbot canvas snapshot [--node <id>]`
### Canvas A2UI
Canvas A2UI is hosted by the **Gateway canvas host** at:
```
http://<gateway-host>:18793/__clawdis__/a2ui/
http://<gateway-host>:18793/__clawdbot__/a2ui/
```
The macOS app simply renders that page in the Canvas panel. The agent can drive it with JSONL **server→client protocol messages** (one JSON object per line):
- `clawdis canvas a2ui push --jsonl <path> [--node <id>]`
- `clawdis canvas a2ui reset [--node <id>]`
- `clawdbot canvas a2ui push --jsonl <path> [--node <id>]`
- `clawdbot canvas a2ui reset [--node <id>]`
`push` expects a JSONL file where **each line is a single JSON object** (parsed and forwarded to the in-page A2UI renderer).
@@ -117,31 +117,31 @@ cat > /tmp/a2ui-v0.8.jsonl <<'EOF'
{"beginRendering":{"surfaceId":"main","root":"root"}}
EOF
clawdis canvas a2ui push --jsonl /tmp/a2ui-v0.8.jsonl --node <id>
clawdbot canvas a2ui push --jsonl /tmp/a2ui-v0.8.jsonl --node <id>
```
Notes:
- This does **not** support the A2UI v0.9 examples using `createSurface`.
- A2UI **fails** if the Gateway canvas host is unreachable (no local fallback).
- `canvas a2ui push` validates JSONL (line numbers on errors) and rejects v0.9 payloads.
- Quick smoke: `clawdis canvas a2ui push --text "Hello from A2UI"` renders a minimal v0.8 view.
- Quick smoke: `clawdbot canvas a2ui push --text "Hello from A2UI"` renders a minimal v0.8 view.
## Triggering agent runs from Canvas (deep links)
Canvas can trigger new agent runs via the macOS app deep-link scheme:
- `clawdis://agent?...`
- `clawdbot://agent?...`
This is intentionally separate from `clawdis-canvas://…` (which is only for serving local Canvas files into the `WKWebView`).
This is intentionally separate from `clawdbot-canvas://…` (which is only for serving local Canvas files into the `WKWebView`).
Suggested patterns:
- HTML: render links/buttons that navigate to `clawdis://agent?message=...`.
- JS: set `window.location.href = 'clawdis://agent?...'` for “run this now” actions.
- HTML: render links/buttons that navigate to `clawdbot://agent?message=...`.
- JS: set `window.location.href = 'clawdbot://agent?...'` for “run this now” actions.
Implementation note (important):
- In `WKWebView`, intercept `clawdis://…` navigations in `WKNavigationDelegate` and forward them to the app, e.g. by calling `DeepLinkHandler.shared.handle(url:)` and returning `.cancel` for the navigation.
- In `WKWebView`, intercept `clawdbot://…` navigations in `WKNavigationDelegate` and forward them to the app, e.g. by calling `DeepLinkHandler.shared.handle(url:)` and returning `.cancel` for the navigation.
Safety:
- Deep links (`clawdis://agent?...`) are always enabled.
- Deep links (`clawdbot://agent?...`) are always enabled.
- Without a `key` query param, the app will prompt for confirmation before invoking the agent.
- With a valid `key`, the run is unattended (no prompt). For Canvas-originated actions, the app injects an internal key automatically.
@@ -149,7 +149,7 @@ Safety:
Recommended defaults:
- `WKWebsiteDataStore.nonPersistent()` for Canvas (ephemeral).
- Navigation policy: allow only `clawdis-canvas://…` (and optionally `about:blank`); open `http/https` externally.
- Navigation policy: allow only `clawdbot-canvas://…` (and optionally `about:blank`); open `http/https` externally.
- Scheme handler must prevent directory traversal: resolved file paths must stay under `<canvasRoot>/<session>/`.
- Disable or tightly scope any JS bridge; prefer query-string/bootstrap config over `window.webkit.messageHandlers` for sensitive data.
@@ -157,5 +157,5 @@ Recommended defaults:
Suggested debugging hooks:
- Enable Web Inspector for Canvas builds (same approach as WebChat).
- Log scheme requests + resolution decisions to OSLog (subsystem `com.clawdis`, category `Canvas`).
- Log scheme requests + resolution decisions to OSLog (subsystem `com.clawdbot`, category `Canvas`).
- Provide a “copy canvas dir” action in debug settings to quickly reveal the session directory in Finder.
docs/mac/child-process.md
+11 -11
View File
@@ -3,17 +3,17 @@ summary: "Running the gateway as a child process of the macOS app and why"
read_when:
- Integrating the mac app with the gateway lifecycle
---
# Clawdis gateway as a child process of the macOS app
# Clawdbot gateway as a child process of the macOS app
Date: 2025-12-06 · Status: draft · Owner: steipete
Note (2025-12-19): the current implementation prefers a **launchd LaunchAgent** that runs the **bundled bun-compiled gateway**. This doc remains as an alternative mode for tighter coupling to the UI.
## Goal
Run the Node-based Clawdis/clawdis gateway as a direct child of the LSUIElement app (instead of a launchd agent) while keeping all TCC-sensitive work inside the Swift app/broker layer and wiring the existing “Clawdis Active” toggle to start/stop the child.
Run the Node-based Clawdbot/clawdbot gateway as a direct child of the LSUIElement app (instead of a launchd agent) while keeping all TCC-sensitive work inside the Swift app/broker layer and wiring the existing “Clawdbot Active” toggle to start/stop the child.
## When to prefer the child-process mode
- You want gateway lifetime strictly coupled to the menu-bar app (dies when the app quits) and controlled by the “Clawdis Active” toggle without touching launchd.
- You want gateway lifetime strictly coupled to the menu-bar app (dies when the app quits) and controlled by the “Clawdbot Active” toggle without touching launchd.
- You’re okay giving up login persistence/auto-restart that launchd provides, or you’ll add your own backoff loop.
- You want simpler log capture and supervision inside the app (no external plist or user-visible LaunchAgent).
@@ -34,11 +34,11 @@ Run the Node-based Clawdis/clawdis gateway as a direct child of the LSUIElement
## Process manager design (Swift Subprocess)
- Add a small `GatewayProcessManager` (Swift) that owns:
- `execution: Execution?` from `Swift Subprocess` to track the child.
- `start(config)` called when “Clawdis Active” flips ON:
- binary: host Node running the bundled gateway under `Clawdis.app/Contents/Resources/Gateway/`
- args: current clawdis entrypoint and flags
- cwd/env: point to `~/.clawdis` as today; inject the expanded PATH so Homebrew Node resolves under launchd
- output: stream stdout/stderr to `/tmp/clawdis-gateway.log` (cap buffer via Subprocess OutputLimits)
- `start(config)` called when “Clawdbot Active” flips ON:
- binary: host Node running the bundled gateway under `Clawdbot.app/Contents/Resources/Gateway/`
- args: current clawdbot entrypoint and flags
- cwd/env: point to `~/.clawdbot` as today; inject the expanded PATH so Homebrew Node resolves under launchd
- output: stream stdout/stderr to `/tmp/clawdbot-gateway.log` (cap buffer via Subprocess OutputLimits)
- restart: optional linear/backoff restart if exit was non-zero and Active is still true
- `stop()` called when Active flips OFF or app terminates: cancel the execution and `waitUntilExit`.
- Wire SwiftUI toggle:
@@ -52,14 +52,14 @@ Run the Node-based Clawdis/clawdis gateway as a direct child of the LSUIElement
- Host runtime should not call TCC APIs directly; keep privileged work inside the app/broker.
## Logging and observability
- Stream child stdout/stderr to `/tmp/clawdis-gateway.log`; surface the last N lines in the Debug tab.
- Stream child stdout/stderr to `/tmp/clawdbot-gateway.log`; surface the last N lines in the Debug tab.
- Emit a user notification (via existing NotificationManager) on crash/exit while Active is true.
- Add a lightweight heartbeat from Node → app (e.g., ping over stdout) so the app can show status in the menu.
## Failure/edge cases
- App crash/quit kills the gateway. Decide if that is acceptable for the deployment tier; otherwise, stick with launchd for production and keep child-process for dev/experiments.
- If the gateway exits repeatedly, back off (e.g., 1s/2s/5s/10s) and give up after N attempts with a menu warning.
- Respect the existing pause semantics: when paused, the broker should return `ok=false, "clawdis paused"`; the gateway should avoid calling privileged routes while paused.
- Respect the existing pause semantics: when paused, the broker should return `ok=false, "clawdbot paused"`; the gateway should avoid calling privileged routes while paused.
## Open questions / follow-ups
- Do we need dual-mode (launchd for prod, child for dev)? If yes, gate via a setting or build flag.
@@ -68,5 +68,5 @@ Run the Node-based Clawdis/clawdis gateway as a direct child of the LSUIElement
## Decision snapshot (current recommendation)
- Keep all TCC surfaces in the Swift app/broker (node commands + PeekabooBridgeHost).
- Implement `GatewayProcessManager` with Swift Subprocess to start/stop the gateway on the “Clawdis Active” toggle.
- Implement `GatewayProcessManager` with Swift Subprocess to start/stop the gateway on the “Clawdbot Active” toggle.
- Maintain the launchd path as a fallback for uptime/login persistence until child-mode proves stable.
docs/mac/dev-setup.md
+9 -9
View File
@@ -1,11 +1,11 @@
---
summary: "Setup guide for developers working on the Clawdis macOS app"
summary: "Setup guide for developers working on the Clawdbot macOS app"
read_when:
- Setting up the macOS development environment
---
# macOS Developer Setup
This guide covers the necessary steps to build and run the Clawdis macOS application from source.
This guide covers the necessary steps to build and run the Clawdbot macOS application from source.
## Prerequisites
@@ -20,7 +20,7 @@ Before building the app, ensure you have the following installed:
## 1. Initialize Submodules
Clawdis depends on several submodules (like `Peekaboo`). You must initialize these recursively:
Clawdbot depends on several submodules (like `Peekaboo`). You must initialize these recursively:
```bash
git submodule update --init --recursive
@@ -36,7 +36,7 @@ pnpm install
## 3. Build and Package the App
To build the macOS app and package it into `dist/Clawdis.app`, run:
To build the macOS app and package it into `dist/Clawdbot.app`, run:
```bash
./scripts/package-mac-app.sh
@@ -48,16 +48,16 @@ If you don't have an Apple Developer ID certificate, the script will automatical
## 4. Install the CLI Helper
The macOS app requires a symlink named `clawdis` in `/usr/local/bin` or `/opt/homebrew/bin` to manage background tasks.
The macOS app requires a symlink named `clawdbot` in `/usr/local/bin` or `/opt/homebrew/bin` to manage background tasks.
**To install it:**
1. Open the Clawdis app.
1. Open the Clawdbot app.
2. Go to the **General** settings tab.
3. Click **"Install CLI helper"** (requires administrator privileges).
Alternatively, you can manually link it from your Admin account:
```bash
sudo ln -sf "/Users/$(whoami)/clawdis/dist/Clawdis.app/Contents/Resources/Relay/clawdis" /usr/local/bin/clawdis
sudo ln -sf "/Users/$(whoami)/clawdbot/dist/Clawdbot.app/Contents/Resources/Relay/clawdbot" /usr/local/bin/clawdbot
```
## Troubleshooting
@@ -68,7 +68,7 @@ If the app crashes when you try to allow **Speech Recognition** or **Microphone*
**Fix:**
1. Reset the TCC permissions:
```bash
tccutil reset All com.clawdis.mac.debug
tccutil reset All com.clawdbot.mac.debug
```
2. If that fails, change the `BUNDLE_ID` temporarily in `scripts/package-mac-app.sh` to force a "clean slate" from macOS.
@@ -78,4 +78,4 @@ If the gateway status stays on "Starting...", check if a zombie process is holdi
```bash
lsof -nP -i :18789
```
Kill any existing `node` or `clawdis` processes listening on that port and restart the app.
Kill any existing `node` or `clawdbot` processes listening on that port and restart the app.
docs/mac/health.md
+2 -2
View File
@@ -21,8 +21,8 @@ How to see whether the WhatsApp Web/Baileys bridge is healthy from the menu bar
- **Connections tab** surfaces provider status + controls for WhatsApp/Telegram (login QR, logout, probe, last disconnect/error).
## How the probe works
- App runs `clawdis health --json` via `ShellExecutor` every ~60s and on demand. The probe loads creds, attempts a short Baileys connect, and reports status without sending messages.
- App runs `clawdbot health --json` via `ShellExecutor` every ~60s and on demand. The probe loads creds, attempts a short Baileys connect, and reports status without sending messages.
- Cache the last good snapshot and the last error separately to avoid flicker; show the timestamp of each.
## When in doubt
- You can still use the CLI flow in `docs/health.md` (`clawdis status`, `clawdis status --deep`, `clawdis health --json`) and tail `/tmp/clawdis/clawdis-*.log` for `web-heartbeat` / `web-reconnect`.
- You can still use the CLI flow in `docs/health.md` (`clawdbot status`, `clawdbot status --deep`, `clawdbot health --json`) and tail `/tmp/clawdbot/clawdbot-*.log` for `web-heartbeat` / `web-reconnect`.
docs/mac/icon.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
summary: "Menu bar icon states and animations for Clawdis on macOS"
summary: "Menu bar icon states and animations for Clawdbot on macOS"
read_when:
- Changing menu bar icon behavior
---
docs/mac/logging.md
+7 -7
View File
@@ -1,5 +1,5 @@
---
summary: "Clawdis logging: rolling diagnostics file log + unified log privacy flags"
summary: "Clawdbot logging: rolling diagnostics file log + unified log privacy flags"
read_when:
- Capturing macOS logs or investigating private data logging
- Debugging voice wake/session lifecycle issues
@@ -7,11 +7,11 @@ read_when:
# Logging (macOS)
## Rolling diagnostics file log (Debug pane)
Clawdis routes macOS app logs through swift-log (unified logging by default) and can write a local, rotating file log to disk when you need a durable capture.
Clawdbot routes macOS app logs through swift-log (unified logging by default) and can write a local, rotating file log to disk when you need a durable capture.
- Verbosity: **Debug pane → Logs → App logging → Verbosity**
- Enable: **Debug pane → Logs → App logging → “Write rolling diagnostics log (JSONL)”**
- Location: `~/Library/Logs/Clawdis/diagnostics.jsonl` (rotates automatically; old files are suffixed with `.1`, `.2`, …)
- Location: `~/Library/Logs/Clawdbot/diagnostics.jsonl` (rotates automatically; old files are suffixed with `.1`, `.2`, …)
- Clear: **Debug pane → Logs → App logging → “Clear”**
Notes:
@@ -22,11 +22,11 @@ Notes:
Unified logging redacts most payloads unless a subsystem opts into `privacy -off`. Per Peter's write-up on macOS [logging privacy shenanigans](https://steipete.me/posts/2025/logging-privacy-shenanigans) (2025) this is controlled by a plist in `/Library/Preferences/Logging/Subsystems/` keyed by the subsystem name. Only new log entries pick up the flag, so enable it before reproducing an issue.
## Enable for Clawdis (`com.clawdis`)
## Enable for Clawdbot (`com.clawdbot`)
- Write the plist to a temp file first, then install it atomically as root:
```bash
cat <<'EOF' >/tmp/com.clawdis.plist
cat <<'EOF' >/tmp/com.clawdbot.plist
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
@@ -39,13 +39,13 @@ cat <<'EOF' >/tmp/com.clawdis.plist
</dict>
</plist>
EOF
sudo install -m 644 -o root -g wheel /tmp/com.clawdis.plist /Library/Preferences/Logging/Subsystems/com.clawdis.plist
sudo install -m 644 -o root -g wheel /tmp/com.clawdbot.plist /Library/Preferences/Logging/Subsystems/com.clawdbot.plist
```
- No reboot is required; logd notices the file quickly, but only new log lines will include private payloads.
- View the richer output with the existing helper, e.g. `./scripts/clawlog.sh --category WebChat --last 5m`.
## Disable after debugging
- Remove the override: `sudo rm /Library/Preferences/Logging/Subsystems/com.clawdis.plist`.
- Remove the override: `sudo rm /Library/Preferences/Logging/Subsystems/com.clawdbot.plist`.
- Optionally run `sudo log config --reload` to force logd to drop the override immediately.
- Remember this surface can include phone numbers and message bodies; keep the plist in place only while you actively need the extra detail.
docs/mac/menu-bar.md
+1 -1
View File
@@ -39,7 +39,7 @@ read_when:
## Status row text (menu)
- While work is active: `<Session role> · <activity label>`
- Examples: `Main · bash: pnpm test`, `Other · read: apps/macos/Sources/Clawdis/AppState.swift`.
- Examples: `Main · bash: pnpm test`, `Other · read: apps/macos/Sources/Clawdbot/AppState.swift`.
- When idle: falls back to the health summary.
## Event ingestion
docs/mac/peekaboo.md
+28 -28
View File
@@ -1,26 +1,26 @@
---
summary: "Plan for integrating Peekaboo automation into Clawdis via PeekabooBridge (socket-based TCC broker)"
summary: "Plan for integrating Peekaboo automation into Clawdbot via PeekabooBridge (socket-based TCC broker)"
read_when:
- Hosting PeekabooBridge in Clawdis.app
- Hosting PeekabooBridge in Clawdbot.app
- Integrating Peekaboo as a submodule
- Changing PeekabooBridge protocol/paths
---
# Peekaboo Bridge in Clawdis (macOS UI automation broker)
# Peekaboo Bridge in Clawdbot (macOS UI automation broker)
## TL;DR
- **Peekaboo removed its XPC helper** and now exposes privileged automation via a **UNIX domain socket bridge** (`PeekabooBridge` / `PeekabooBridgeHost`, socket name `bridge.sock`).
- Clawdis integrates by **optionally hosting the same bridge** inside **Clawdis.app** (user-toggleable). The primary client is the **`peekaboo` CLI** (installed via npm); Clawdis does not need its own `ui …` CLI surface.
- For **visualizations**, we keep them in **Peekaboo.app** (best UX); Clawdis stays a thin broker host. No visualizer toggle in Clawdis.
- Clawdbot integrates by **optionally hosting the same bridge** inside **Clawdbot.app** (user-toggleable). The primary client is the **`peekaboo` CLI** (installed via npm); Clawdbot does not need its own `ui …` CLI surface.
- For **visualizations**, we keep them in **Peekaboo.app** (best UX); Clawdbot stays a thin broker host. No visualizer toggle in Clawdbot.
Non-goals:
- No auto-launching Peekaboo.app.
- No onboarding deep links from the automation endpoint (Clawdis onboarding already handles permissions).
- No AI provider/agent runtime dependencies in Clawdis (avoid pulling Tachikoma/MCP into the Clawdis app/CLI).
- No onboarding deep links from the automation endpoint (Clawdbot onboarding already handles permissions).
- No AI provider/agent runtime dependencies in Clawdbot (avoid pulling Tachikoma/MCP into the Clawdbot app/CLI).
## Big refactor (Dec 2025): XPC → Bridge
Peekaboo’s privileged execution moved from “CLI → XPC helper” to “CLI → socket bridge host”. For Clawdis this is a win:
Peekaboo’s privileged execution moved from “CLI → XPC helper” to “CLI → socket bridge host”. For Clawdbot this is a win:
- It matches the existing “local socket + codesign checks” approach.
- It lets us piggyback on **either** Peekaboo.app’s permissions **or** Clawdis.app’s permissions (whichever is running).
- It lets us piggyback on **either** Peekaboo.app’s permissions **or** Clawdbot.app’s permissions (whichever is running).
- It avoids “two apps with two TCC bubbles” unless needed.
Reference (Peekaboo submodule): `docs/bridge-host.md`.
@@ -30,23 +30,23 @@ Reference (Peekaboo submodule): `docs/bridge-host.md`.
- **Bridge hosts** (provide TCC-backed automation):
- **Peekaboo.app** (preferred; also provides visualizations + controls)
- **Claude.app** (secondary; lets `peekaboo` reuse Claude Desktop’s granted permissions)
- **Clawdis.app** (secondary; “thin host” only)
- **Clawdbot.app** (secondary; “thin host” only)
- **Bridge clients** (trigger single actions):
- `peekaboo …` (preferred; humans + agents)
- Optional: Clawdis/Node shells out to `peekaboo` when it needs UI automation/capture
- Optional: Clawdbot/Node shells out to `peekaboo` when it needs UI automation/capture
### Host discovery (client-side)
Order is deliberate:
1. Peekaboo.app host (full UX)
2. Claude.app host (piggyback on Claude Desktop permissions)
3. Clawdis.app host (piggyback on Clawdis permissions)
3. Clawdbot.app host (piggyback on Clawdbot permissions)
Socket paths (convention; exact paths must match Peekaboo):
- Peekaboo: `~/Library/Application Support/Peekaboo/bridge.sock`
- Claude: `~/Library/Application Support/Claude/bridge.sock`
- Clawdis: `~/Library/Application Support/clawdis/bridge.sock`
- Clawdbot: `~/Library/Application Support/clawdbot/bridge.sock`
No auto-launch: if a host isn’t reachable, the command fails with a clear error (start Peekaboo.app, Claude.app, or Clawdis.app).
No auto-launch: if a host isn’t reachable, the command fails with a clear error (start Peekaboo.app, Claude.app, or Clawdbot.app).
Override (debugging): set `PEEKABOO_BRIDGE_SOCKET=/path/to/bridge.sock`.
@@ -58,22 +58,22 @@ Override (debugging): set `PEEKABOO_BRIDGE_SOCKET=/path/to/bridge.sock`.
## Dependency strategy (submodule)
Integrate Peekaboo via git submodule (nested submodules are OK).
Path in Clawdis repo:
Path in Clawdbot repo:
- `./Peekaboo` (Swabble-style; keep stable so SwiftPM path deps don’t churn).
What Clawdis should use:
What Clawdbot should use:
- **Client side**: `PeekabooBridge` (socket client + protocol models).
- **Host side (Clawdis.app)**: `PeekabooBridgeHost` + the minimal Peekaboo services needed to implement operations.
- **Host side (Clawdbot.app)**: `PeekabooBridgeHost` + the minimal Peekaboo services needed to implement operations.
What Clawdis should *not* embed:
What Clawdbot should *not* embed:
- **Visualizer UI**: keep it in Peekaboo.app for now (toggle + controls live there).
- **XPC**: don’t reintroduce helper targets; use the bridge.
## IPC / CLI surface
### No `clawdis ui …`
We avoid a parallel “Clawdis UI automation CLI”. Instead:
### No `clawdbot ui …`
We avoid a parallel “Clawdbot UI automation CLI”. Instead:
- `peekaboo` is the user/agent-facing CLI surface for automation and capture.
- Clawdis.app can host PeekabooBridge as a **thin TCC broker** so Peekaboo can piggyback on Clawdis permissions when Peekaboo.app isn’t running.
- Clawdbot.app can host PeekabooBridge as a **thin TCC broker** so Peekaboo can piggyback on Clawdbot permissions when Peekaboo.app isn’t running.
### Diagnostics
Use Peekaboo’s built-in diagnostics to see which host would be used:
@@ -94,7 +94,7 @@ Standardize for the CLI (agent-friendly): **top-left origin per screen**.
Proposed request shape:
- Requests accept `screenIndex` + `{x, y}` in that screen’s local coordinate space.
- Clawdis.app converts to global CG coordinates using `NSScreen.screens[screenIndex].frame.origin`.
- Clawdbot.app converts to global CG coordinates using `NSScreen.screens[screenIndex].frame.origin`.
- Responses should echo both:
- The resolved `screenIndex`
- The local `{x, y}` and bounds
@@ -136,15 +136,15 @@ Practical flow (agent-friendly):
## Visualizer integration
Keep visualizations in **Peekaboo.app** for now.
- Clawdis hosts the bridge, but does not render overlays.
- Clawdbot hosts the bridge, but does not render overlays.
- Any “visualizer enabled/disabled” setting is controlled in Peekaboo.app.
## Screenshots (legacy → Peekaboo takeover)
Clawdis should not grow a separate screenshot CLI surface.
Clawdbot should not grow a separate screenshot CLI surface.
Migration plan:
- Use `peekaboo capture …` / `peekaboo see …` (returns a file path, default temp directory).
- Once Clawdis’ legacy screenshot plumbing is replaced, remove it cleanly (no aliases).
- Once Clawdbot’ legacy screenshot plumbing is replaced, remove it cleanly (no aliases).
## Permissions behavior
If required permissions are missing:
@@ -164,7 +164,7 @@ Debug-only escape hatch (development convenience):
## Next integration steps (after this doc)
1. Add Peekaboo as a git submodule (nested submodules OK).
2. Host `PeekabooBridgeHost` inside Clawdis.app behind a single setting (“Enable Peekaboo Bridge”, default on).
3. Ensure Clawdis hosts the bridge at `~/Library/Application Support/clawdis/bridge.sock` and speaks the PeekabooBridge JSON protocol.
4. Validate with `peekaboo bridge status --verbose` that Peekaboo can select Clawdis as the fallback host (no auto-launch).
2. Host `PeekabooBridgeHost` inside Clawdbot.app behind a single setting (“Enable Peekaboo Bridge”, default on).
3. Ensure Clawdbot hosts the bridge at `~/Library/Application Support/clawdbot/bridge.sock` and speaks the PeekabooBridge JSON protocol.
4. Validate with `peekaboo bridge status --verbose` that Peekaboo can select Clawdbot as the fallback host (no auto-launch).
5. Keep all protocol decisions aligned with Peekaboo (coordinate system, element IDs, snapshot scoping, error envelopes).
docs/mac/permissions.md
+3 -3
View File
@@ -12,7 +12,7 @@ app's code signature, bundle identifier, and on-disk path. If any of those chang
macOS treats the app as new and may drop or hide prompts.
## Requirements for stable permissions
- Same path: run the app from a fixed location (for Clawdis, `dist/Clawdis.app`).
- Same path: run the app from a fixed location (for Clawdbot, `dist/Clawdbot.app`).
- Same bundle identifier: changing the bundle ID creates a new permission identity.
- Signed app: unsigned or ad-hoc signed builds do not persist permissions.
- Consistent signature: use a real Apple Development or Developer ID certificate
@@ -31,8 +31,8 @@ grants, and prompts can disappear entirely until the stale entries are cleared.
Example resets (replace bundle ID as needed):
```bash
sudo tccutil reset Accessibility com.clawdis.mac
sudo tccutil reset ScreenCapture com.clawdis.mac
sudo tccutil reset Accessibility com.clawdbot.mac
sudo tccutil reset ScreenCapture com.clawdbot.mac
sudo tccutil reset AppleEvents
```
docs/mac/release.md
+17 -17
View File
@@ -1,11 +1,11 @@
---
summary: "Clawdis macOS release checklist (Sparkle feed, packaging, signing)"
summary: "Clawdbot macOS release checklist (Sparkle feed, packaging, signing)"
read_when:
- Cutting or validating a Clawdis macOS release
- Cutting or validating a Clawdbot macOS release
- Updating the Sparkle appcast or feed assets
---
# Clawdis macOS release (Sparkle)
# Clawdbot macOS release (Sparkle)
This app now ships Sparkle auto-updates. Release builds must be Developer ID–signed, zipped, and published with a signed appcast entry.
@@ -13,10 +13,10 @@ This app now ships Sparkle auto-updates. Release builds must be Developer ID–s
- Developer ID Application cert installed (`Developer ID Application: Peter Steinberger (Y5PE65HELJ)` is expected).
- Sparkle private key path set in the environment as `SPARKLE_PRIVATE_KEY_FILE`; key lives in `/Users/steipete/Library/CloudStorage/Dropbox/Backup/Sparkle` (same key as Trimmy; public key baked into Info.plist).
- Notary credentials (keychain profile or API key) for `xcrun notarytool` if you want Gatekeeper-safe DMG/zip distribution.
- We use a Keychain profile named `clawdis-notary`, created from App Store Connect API key env vars in your shell profile:
- We use a Keychain profile named `clawdbot-notary`, created from App Store Connect API key env vars in your shell profile:
- `APP_STORE_CONNECT_API_KEY_P8`, `APP_STORE_CONNECT_KEY_ID`, `APP_STORE_CONNECT_ISSUER_ID`
- `echo "$APP_STORE_CONNECT_API_KEY_P8" | sed 's/\\n/\n/g' > /tmp/clawdis-notary.p8`
- `xcrun notarytool store-credentials "clawdis-notary" --key /tmp/clawdis-notary.p8 --key-id "$APP_STORE_CONNECT_KEY_ID" --issuer "$APP_STORE_CONNECT_ISSUER_ID"`
- `echo "$APP_STORE_CONNECT_API_KEY_P8" | sed 's/\\n/\n/g' > /tmp/clawdbot-notary.p8`
- `xcrun notarytool store-credentials "clawdbot-notary" --key /tmp/clawdbot-notary.p8 --key-id "$APP_STORE_CONNECT_KEY_ID" --issuer "$APP_STORE_CONNECT_ISSUER_ID"`
- `pnpm` deps installed (`pnpm install --config.node-linker=hoisted`).
- Sparkle tools are fetched automatically via SwiftPM at `apps/macos/.build/artifacts/sparkle/Sparkle/bin/` (`sign_update`, `generate_appcast`, etc.).
@@ -28,7 +28,7 @@ Notes:
```bash
# From repo root; set release IDs so Sparkle feed is enabled.
# APP_BUILD must be numeric + monotonic for Sparkle compare.
BUNDLE_ID=com.clawdis.mac \
BUNDLE_ID=com.clawdbot.mac \
APP_VERSION=0.1.0 \
APP_BUILD="$(git rev-list --count HEAD)" \
BUILD_CONFIG=release \
@@ -36,17 +36,17 @@ SIGN_IDENTITY="Developer ID Application: Peter Steinberger (Y5PE65HELJ)" \
scripts/package-mac-app.sh
# Zip for distribution (includes resource forks for Sparkle delta support)
ditto -c -k --sequesterRsrc --keepParent dist/Clawdis.app dist/Clawdis-0.1.0.zip
ditto -c -k --sequesterRsrc --keepParent dist/Clawdbot.app dist/Clawdbot-0.1.0.zip
# Optional: also build a styled DMG for humans (drag to /Applications)
scripts/create-dmg.sh dist/Clawdis.app dist/Clawdis-0.1.0.dmg
scripts/create-dmg.sh dist/Clawdbot.app dist/Clawdbot-0.1.0.dmg
# Recommended: build + notarize/staple zip + DMG
# First, create a keychain profile once:
# xcrun notarytool store-credentials "clawdis-notary" \
# xcrun notarytool store-credentials "clawdbot-notary" \
# --apple-id "<apple-id>" --team-id "<team-id>" --password "<app-specific-password>"
NOTARIZE=1 NOTARYTOOL_PROFILE=clawdis-notary \
BUNDLE_ID=com.clawdis.mac \
NOTARIZE=1 NOTARYTOOL_PROFILE=clawdbot-notary \
BUNDLE_ID=com.clawdbot.mac \
APP_VERSION=0.1.0 \
APP_BUILD="$(git rev-list --count HEAD)" \
BUILD_CONFIG=release \
@@ -54,22 +54,22 @@ SIGN_IDENTITY="Developer ID Application: Peter Steinberger (Y5PE65HELJ)" \
scripts/package-mac-dist.sh
# Optional: ship dSYM alongside the release
ditto -c -k --keepParent apps/macos/.build/release/Clawdis.app.dSYM dist/Clawdis-0.1.0.dSYM.zip
ditto -c -k --keepParent apps/macos/.build/release/Clawdbot.app.dSYM dist/Clawdbot-0.1.0.dSYM.zip
```
## Appcast entry
Use the release note generator so Sparkle renders formatted HTML notes:
```bash
SPARKLE_PRIVATE_KEY_FILE=/Users/steipete/Library/CloudStorage/Dropbox/Backup/Sparkle/ed25519-private-key scripts/make_appcast.sh dist/Clawdis-0.1.0.zip https://raw.githubusercontent.com/steipete/clawdis/main/appcast.xml
SPARKLE_PRIVATE_KEY_FILE=/Users/steipete/Library/CloudStorage/Dropbox/Backup/Sparkle/ed25519-private-key scripts/make_appcast.sh dist/Clawdbot-0.1.0.zip https://raw.githubusercontent.com/clawdbot/clawdbot/main/appcast.xml
```
Generates HTML release notes from `CHANGELOG.md` (via `scripts/changelog-to-html.sh`) and embeds them in the appcast entry.
Commit the updated `appcast.xml` alongside the release assets (zip + dSYM) when publishing.
## Publish & verify
- Upload `Clawdis-0.1.0.zip` (and `Clawdis-0.1.0.dSYM.zip`) to the GitHub release for tag `v0.1.0`.
- Ensure the raw appcast URL matches the baked feed: `https://raw.githubusercontent.com/steipete/clawdis/main/appcast.xml`.
- Upload `Clawdbot-0.1.0.zip` (and `Clawdbot-0.1.0.dSYM.zip`) to the GitHub release for tag `v0.1.0`.
- Ensure the raw appcast URL matches the baked feed: `https://raw.githubusercontent.com/clawdbot/clawdbot/main/appcast.xml`.
- Sanity checks:
- `curl -I https://raw.githubusercontent.com/steipete/clawdis/main/appcast.xml` returns 200.
- `curl -I https://raw.githubusercontent.com/clawdbot/clawdbot/main/appcast.xml` returns 200.
- `curl -I <enclosure url>` returns 200 after assets upload.
- On a previous public build, run “Check for Updates…” from the About tab and verify Sparkle installs the new build cleanly.
docs/mac/remote.md
+14 -14
View File
@@ -1,32 +1,32 @@
---
summary: "macOS app flow for controlling a remote Clawdis gateway over SSH"
summary: "macOS app flow for controlling a remote Clawdbot gateway over SSH"
read_when:
- Setting up or debugging remote mac control
---
# Remote Clawdis (macOS ⇄ remote host)
# Remote Clawdbot (macOS ⇄ remote host)
Updated: 2025-12-08
This flow lets the macOS app act as a full remote control for a Clawdis gateway running on another host (e.g. a Mac Studio). All features—health checks, Voice Wake forwarding, and Web Chat—reuse the same remote SSH configuration from *Settings → General*.
This flow lets the macOS app act as a full remote control for a Clawdbot gateway running on another host (e.g. a Mac Studio). All features—health checks, Voice Wake forwarding, and Web Chat—reuse the same remote SSH configuration from *Settings → General*.
## Modes
- **Local (this Mac)**: Everything runs on the laptop. No SSH involved.
- **Remote over SSH**: Clawdis commands are executed on the remote host. The mac app opens an SSH connection with `-o BatchMode` plus your chosen identity/key.
- **Remote over SSH**: Clawdbot commands are executed on the remote host. The mac app opens an SSH connection with `-o BatchMode` plus your chosen identity/key.
## Prereqs on the remote host
1) Install Node + pnpm and build/install the Clawdis CLI (`pnpm install && pnpm build && pnpm link --global`).
2) Ensure `clawdis` is on PATH for non-interactive shells (symlink into `/usr/local/bin` or `/opt/homebrew/bin` if needed).
1) Install Node + pnpm and build/install the Clawdbot CLI (`pnpm install && pnpm build && pnpm link --global`).
2) Ensure `clawdbot` is on PATH for non-interactive shells (symlink into `/usr/local/bin` or `/opt/homebrew/bin` if needed).
3) Open SSH with key auth. We recommend **Tailscale** IPs for stable reachability off-LAN.
## macOS app setup
1) Open *Settings → General*.
2) Under **Clawdis runs**, pick **Remote over SSH** and set:
2) Under **Clawdbot runs**, pick **Remote over SSH** and set:
- **SSH target**: `user@host` (optional `:port`).
- If the gateway is on the same LAN and advertises Bonjour, pick it from the discovered list to auto-fill this field.
- **Identity file** (advanced): path to your key.
- **Project root** (advanced): remote checkout path used for commands.
- **CLI path** (advanced): optional path to a runnable `clawdis` entrypoint/binary (auto-filled when advertised).
3) Hit **Test remote**. Success indicates the remote `clawdis status --json` runs correctly. Failures usually mean PATH/CLI issues; exit 127 means the CLI isn’t found remotely.
- **CLI path** (advanced): optional path to a runnable `clawdbot` entrypoint/binary (auto-filled when advertised).
3) Hit **Test remote**. Success indicates the remote `clawdbot status --json` runs correctly. Failures usually mean PATH/CLI issues; exit 127 means the CLI isn’t found remotely.
4) Health checks and Web Chat will now run through this SSH tunnel automatically.
## Web Chat over SSH
@@ -38,20 +38,20 @@ This flow lets the macOS app act as a full remote control for a Clawdis gateway
- Nodes advertise their permission state via `node.list` / `node.describe` so agents know what’s available.
## WhatsApp login flow (remote)
- Run `clawdis login --verbose` **on the remote host**. Scan the QR with WhatsApp on your phone.
- Run `clawdbot login --verbose` **on the remote host**. Scan the QR with WhatsApp on your phone.
- Re-run login on that host if auth expires. Health check will surface link problems.
## Troubleshooting
- **exit 127 / not found**: `clawdis` isn’t on PATH for non-login shells. Add it to `/etc/paths`, your shell rc, or symlink into `/usr/local/bin`/`/opt/homebrew/bin`.
- **Health probe failed**: check SSH reachability, PATH, and that Baileys is logged in (`clawdis status --json`).
- **exit 127 / not found**: `clawdbot` isn’t on PATH for non-login shells. Add it to `/etc/paths`, your shell rc, or symlink into `/usr/local/bin`/`/opt/homebrew/bin`.
- **Health probe failed**: check SSH reachability, PATH, and that Baileys is logged in (`clawdbot status --json`).
- **Web Chat stuck**: confirm the gateway is running on the remote host and the forwarded port matches the gateway WS port; the UI requires a healthy WS connection.
- **Voice Wake**: trigger phrases are forwarded automatically in remote mode; no separate forwarder is needed.
## Notification sounds
Pick sounds per notification from scripts with `clawdis` and `node.invoke`, e.g.:
Pick sounds per notification from scripts with `clawdbot` and `node.invoke`, e.g.:
```bash
clawdis nodes notify --node <id> --title "Ping" --body "Remote gateway ready" --sound Glass
clawdbot nodes notify --node <id> --title "Ping" --body "Remote gateway ready" --sound Glass
```
There is no global “default sound” toggle in the app anymore; callers choose a sound (or none) per request.
docs/mac/signing.md
+5 -5
View File
@@ -7,11 +7,11 @@ read_when:
This app is usually built from `scripts/package-mac-app.sh`, which now:
- sets a stable debug bundle identifier: `com.clawdis.mac.debug`
- sets a stable debug bundle identifier: `com.clawdbot.mac.debug`
- writes the Info.plist with that bundle id (override via `BUNDLE_ID=...`)
- calls `scripts/codesign-mac-app.sh` to sign the main binary, bundled CLI, and app bundle so macOS treats each rebuild as the same signed bundle and keeps TCC permissions (notifications, accessibility, screen recording, mic, speech). For stable permissions, use a real signing identity; ad-hoc is opt-in and fragile (see `docs/mac/permissions.md`).
- uses `CODESIGN_TIMESTAMP=auto` by default; it enables trusted timestamps for Developer ID signatures. Set `CODESIGN_TIMESTAMP=off` to skip timestamping (offline debug builds).
- inject build metadata into Info.plist: `ClawdisBuildTimestamp` (UTC) and `ClawdisGitCommit` (short hash) so the About pane can show build, git, and debug/release channel.
- inject build metadata into Info.plist: `ClawdbotBuildTimestamp` (UTC) and `ClawdbotGitCommit` (short hash) so the About pane can show build, git, and debug/release channel.
- **Packaging requires Bun**: The embedded gateway relay is compiled using `bun`. Ensure it is installed (`curl -fsSL https://bun.sh/install | bash`).
- reads `SIGN_IDENTITY` from the environment. Add `export SIGN_IDENTITY="Apple Development: Your Name (TEAMID)"` (or your Developer ID Application cert) to your shell rc to always sign with your cert. Ad-hoc signing requires explicit opt-in via `ALLOW_ADHOC_SIGNING=1` or `SIGN_IDENTITY="-"` (not recommended for permission testing).
@@ -31,11 +31,11 @@ When signing with `SIGN_IDENTITY="-"` (ad-hoc), the script automatically disable
## Build metadata for About
`package-mac-app.sh` stamps the bundle with:
- `ClawdisBuildTimestamp`: ISO8601 UTC at package time
- `ClawdisGitCommit`: short git hash (or `unknown` if unavailable)
- `ClawdbotBuildTimestamp`: ISO8601 UTC at package time
- `ClawdbotGitCommit`: short git hash (or `unknown` if unavailable)
The About tab reads these keys to show version, build date, git commit, and whether it’s a debug build (via `#if DEBUG`). Run the packager to refresh these values after code changes.
## Why
TCC permissions are tied to the bundle identifier *and* code signature. Unsigned debug builds with changing UUIDs were causing macOS to forget grants after each rebuild. Signing the binaries (ad‑hoc by default) and keeping a fixed bundle id/path (`dist/Clawdis.app`) preserves the grants between builds, matching the VibeTunnel approach.
TCC permissions are tied to the bundle identifier *and* code signature. Unsigned debug builds with changing UUIDs were causing macOS to forget grants after each rebuild. Signing the binaries (ad‑hoc by default) and keeping a fixed bundle id/path (`dist/Clawdbot.app`) preserves the grants between builds, matching the VibeTunnel approach.
docs/mac/skills.md
+4 -4
View File
@@ -6,21 +6,21 @@ read_when:
---
# Skills (macOS)
The macOS app surfaces Clawdis skills via the gateway; it does not parse skills locally.
The macOS app surfaces Clawdbot skills via the gateway; it does not parse skills locally.
## Data source
- `skills.status` (gateway) returns all skills plus eligibility and missing requirements
(including allowlist blocks for bundled skills).
- Requirements are derived from `metadata.clawdis.requires` in each `SKILL.md`.
- Requirements are derived from `metadata.clawdbot.requires` in each `SKILL.md`.
## Install actions
- `metadata.clawdis.install` defines install options (brew/node/go/uv).
- `metadata.clawdbot.install` defines install options (brew/node/go/uv).
- The app calls `skills.install` to run installers on the gateway host.
- The gateway surfaces only one preferred installer when multiple are provided
(brew when available, otherwise node manager from `skills.install`, default npm).
## Env/API keys
- The app stores keys in `~/.clawdis/clawdis.json` under `skills.entries.<skillKey>`.
- The app stores keys in `~/.clawdbot/clawdbot.json` under `skills.entries.<skillKey>`.
- `skills.update` patches `enabled`, `apiKey`, and `env`.
## Remote mode
docs/mac/voice-overlay.md
+2 -2
View File
@@ -32,14 +32,14 @@ Audience: macOS app contributors. Goal: keep the voice overlay predictable when
- Push-to-talk: no delay; wake-word: optional delay for auto-send.
- Apply a short cooldown to the wake runtime after push-to-talk finishes so wake-word doesn’t immediately retrigger.
5. **Logging**
- Coordinator emits `.info` logs in subsystem `com.clawdis`, categories `voicewake.overlay` and `voicewake.chime`.
- Coordinator emits `.info` logs in subsystem `com.clawdbot`, categories `voicewake.overlay` and `voicewake.chime`.
- Key events: `session_started`, `adopted_by_push_to_talk`, `partial`, `finalized`, `send`, `dismiss`, `cancel`, `cooldown`.
### Debugging checklist
- Stream logs while reproducing a sticky overlay:
```bash
sudo log stream --predicate 'subsystem == "com.clawdis" AND category CONTAINS "voicewake"' --level info --style compact
sudo log stream --predicate 'subsystem == "com.clawdbot" AND category CONTAINS "voicewake"' --level info --style compact
```
- Verify only one active session token; stale callbacks should be dropped by the coordinator.
- Ensure push-to-talk release always calls `endCapture` with the active token; if text is empty, expect `dismiss` without chime or send.
docs/mac/webchat.md
+3 -3
View File
@@ -12,11 +12,11 @@ The macOS menu bar app shows the WebChat UI as a native SwiftUI view and reuses
## Launch & debugging
- Manual: Lobster menu → “Open Chat”.
- Auto-open for testing: run `dist/Clawdis.app/Contents/MacOS/Clawdis --webchat` (or pass `--webchat` to the binary launched by launchd). The window opens on startup.
- Logs: see `./scripts/clawlog.sh` (subsystem `com.clawdis`, category `WebChatSwiftUI`).
- Auto-open for testing: run `dist/Clawdbot.app/Contents/MacOS/Clawdbot --webchat` (or pass `--webchat` to the binary launched by launchd). The window opens on startup.
- Logs: see `./scripts/clawlog.sh` (subsystem `com.clawdbot`, category `WebChatSwiftUI`).
## How it’s wired
- Implementation: `apps/macos/Sources/Clawdis/WebChatSwiftUI.swift` hosts `ClawdisChatUI` and speaks to the Gateway over `GatewayConnection`.
- Implementation: `apps/macos/Sources/Clawdbot/WebChatSwiftUI.swift` hosts `ClawdbotChatUI` and speaks to the Gateway over `GatewayConnection`.
- Data plane: Gateway WebSocket methods `chat.history`, `chat.send`, `chat.abort`; events `chat`, `agent`, `presence`, `tick`, `health`.
- Session: usually primary (`main`); multiple transports (WhatsApp/Telegram/Discord/Desktop) share the same key. The onboarding flow uses a dedicated `onboarding` session to keep first-run setup separate.
docs/mac/xpc.md
+5 -5
View File
@@ -1,11 +1,11 @@
---
summary: "macOS IPC architecture for Clawdis app, gateway node bridge, and PeekabooBridge"
summary: "macOS IPC architecture for Clawdbot app, gateway node bridge, and PeekabooBridge"
read_when:
- Editing IPC contracts or menu bar app IPC
---
# Clawdis macOS IPC architecture (Dec 2025)
# Clawdbot macOS IPC architecture (Dec 2025)
**Current model:** there is **no local control socket** and no `clawdis-mac` CLI. All agent actions go through the Gateway WebSocket and `node.invoke`. UI automation still uses PeekabooBridge.
**Current model:** there is **no local control socket** and no `clawdbot-mac` CLI. All agent actions go through the Gateway WebSocket and `node.invoke`. UI automation still uses PeekabooBridge.
## Goals
- Single GUI app instance that owns all TCC-facing work (notifications, screen recording, mic, speech, AppleScript).
@@ -19,9 +19,9 @@ read_when:
### PeekabooBridge (UI automation)
- UI automation uses a separate UNIX socket named `bridge.sock` and the PeekabooBridge JSON protocol.
- Host preference order (client-side): Peekaboo.app → Claude.app → Clawdis.app → local execution.
- Host preference order (client-side): Peekaboo.app → Claude.app → Clawdbot.app → local execution.
- Security: bridge hosts require TeamID `Y5PE65HELJ`; DEBUG-only same-UID escape hatch is guarded by `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1` (Peekaboo convention).
- See: `docs/mac/peekaboo.md` for the Clawdis plan and naming.
- See: `docs/mac/peekaboo.md` for the Clawdbot plan and naming.
### Mach/XPC (future direction)
- Still optional for internal app services, but **not required** for automation now that node.invoke is the surface.
docs/nix.md
+9 -9
View File
@@ -1,31 +1,31 @@
---
summary: "Running Clawdis under Nix (config, state, and packaging expectations)"
summary: "Running Clawdbot under Nix (config, state, and packaging expectations)"
read_when:
- Building Clawdis with Nix
- Building Clawdbot with Nix
- Debugging Nix-mode behavior
---
# Nix mode
Clawdis supports a **Nix mode** that makes configuration deterministic and disables auto-install flows.
Clawdbot supports a **Nix mode** that makes configuration deterministic and disables auto-install flows.
Enable it by exporting:
```
CLAWDIS_NIX_MODE=1
CLAWDBOT_NIX_MODE=1
```
On macOS, the GUI app does not automatically inherit shell env vars. You can
also enable Nix mode via defaults:
```
defaults write com.clawdis.mac clawdis.nixMode -bool true
defaults write com.clawdbot.mac clawdbot.nixMode -bool true
```
## Config + state paths
Clawdis reads JSON5 config from `CLAWDIS_CONFIG_PATH` and stores mutable data in `CLAWDIS_STATE_DIR`.
Clawdbot reads JSON5 config from `CLAWDBOT_CONFIG_PATH` and stores mutable data in `CLAWDBOT_STATE_DIR`.
- `CLAWDIS_STATE_DIR` (default: `~/.clawdis`)
- `CLAWDIS_CONFIG_PATH` (default: `$CLAWDIS_STATE_DIR/clawdis.json`)
- `CLAWDBOT_STATE_DIR` (default: `~/.clawdbot`)
- `CLAWDBOT_CONFIG_PATH` (default: `$CLAWDBOT_STATE_DIR/clawdbot.json`)
When running under Nix, set these explicitly to Nix-managed locations so runtime state and config
stay out of the immutable store.
@@ -41,7 +41,7 @@ stay out of the immutable store.
The macOS packaging flow expects a stable Info.plist template at:
```
apps/macos/Sources/Clawdis/Resources/Info.plist
apps/macos/Sources/Clawdbot/Resources/Info.plist
```
`scripts/package-mac-app.sh` copies this template into the app bundle and patches dynamic fields
docs/nodes.md
+25 -25
View File
@@ -10,7 +10,7 @@ read_when:
A **node** is a companion device (iOS/Android today) that connects to the Gateway over the **Bridge** and exposes a command surface (e.g. `canvas.*`, `camera.*`, `system.*`) via `node.invoke`.
macOS can also run in **node mode**: the menubar app connects to the Gateway’s bridge and exposes its local canvas/camera commands as a node (so `clawdis nodes …` works against this Mac).
macOS can also run in **node mode**: the menubar app connects to the Gateway’s bridge and exposes its local canvas/camera commands as a node (so `clawdbot nodes …` works against this Mac).
## Pairing + status
@@ -19,12 +19,12 @@ Pairing is gateway-owned and approval-based. See `docs/gateway/pairing.md` for t
Quick CLI:
```bash
clawdis nodes pending
clawdis nodes approve <requestId>
clawdis nodes reject <requestId>
clawdis nodes status
clawdis nodes describe --node <idOrNameOrIp>
clawdis nodes rename --node <idOrNameOrIp> --name "Kitchen iPad"
clawdbot nodes pending
clawdbot nodes approve <requestId>
clawdbot nodes reject <requestId>
clawdbot nodes status
clawdbot nodes describe --node <idOrNameOrIp>
clawdbot nodes rename --node <idOrNameOrIp> --name "Kitchen iPad"
```
Notes:
@@ -35,7 +35,7 @@ Notes:
Low-level (raw RPC):
```bash
clawdis nodes invoke --node <idOrNameOrIp> --command canvas.eval --params '{"javaScript":"location.href"}'
clawdbot nodes invoke --node <idOrNameOrIp> --command canvas.eval --params '{"javaScript":"location.href"}'
```
Higher-level helpers exist for the common “give the agent a MEDIA attachment” workflows.
@@ -47,15 +47,15 @@ If the node is showing the Canvas (WebView), `canvas.snapshot` returns `{ format
CLI helper (writes to a temp file and prints `MEDIA:<path>`):
```bash
clawdis nodes canvas snapshot --node <idOrNameOrIp> --format png
clawdis nodes canvas snapshot --node <idOrNameOrIp> --format jpg --max-width 1200 --quality 0.9
clawdbot nodes canvas snapshot --node <idOrNameOrIp> --format png
clawdbot nodes canvas snapshot --node <idOrNameOrIp> --format jpg --max-width 1200 --quality 0.9
```
Simple shortcut (auto-picks a single connected node if possible):
```bash
clawdis canvas snapshot --format png
clawdis canvas snapshot --format jpg --max-width 1200 --quality 0.9
clawdbot canvas snapshot --format png
clawdbot canvas snapshot --format jpg --max-width 1200 --quality 0.9
```
## Photos + videos (node camera)
@@ -63,15 +63,15 @@ clawdis canvas snapshot --format jpg --max-width 1200 --quality 0.9
Photos (`jpg`):
```bash
clawdis nodes camera snap --node <idOrNameOrIp> # default: both facings (2 MEDIA lines)
clawdis nodes camera snap --node <idOrNameOrIp> --facing front
clawdbot nodes camera snap --node <idOrNameOrIp> # default: both facings (2 MEDIA lines)
clawdbot nodes camera snap --node <idOrNameOrIp> --facing front
```
Video clips (`mp4`):
```bash
clawdis nodes camera clip --node <idOrNameOrIp> --duration 10s
clawdis nodes camera clip --node <idOrNameOrIp> --duration 3000 --no-audio
clawdbot nodes camera clip --node <idOrNameOrIp> --duration 10s
clawdbot nodes camera clip --node <idOrNameOrIp> --duration 3000 --no-audio
```
Notes:
@@ -84,8 +84,8 @@ Notes:
Nodes expose `screen.record` (mp4). Example:
```bash
clawdis nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10
clawdis nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10 --no-audio
clawdbot nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10
clawdbot nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10 --no-audio
```
Notes:
@@ -101,8 +101,8 @@ Nodes expose `location.get` when Location is enabled in settings.
CLI helper:
```bash
clawdis nodes location get --node <idOrNameOrIp>
clawdis nodes location get --node <idOrNameOrIp> --accuracy precise --max-age 15000 --location-timeout 10000
clawdbot nodes location get --node <idOrNameOrIp>
clawdbot nodes location get --node <idOrNameOrIp> --accuracy precise --max-age 15000 --location-timeout 10000
```
Notes:
@@ -117,7 +117,7 @@ Android nodes can expose `sms.send` when the user grants **SMS** permission and
Low-level invoke:
```bash
clawdis nodes invoke --node <idOrNameOrIp> --command sms.send --params '{"to":"+15555550123","message":"Hello from Clawdis"}'
clawdbot nodes invoke --node <idOrNameOrIp> --command sms.send --params '{"to":"+15555550123","message":"Hello from Clawdbot"}'
```
Notes:
@@ -131,8 +131,8 @@ The macOS node exposes `system.run` and `system.notify`.
Examples:
```bash
clawdis nodes run --node <idOrNameOrIp> -- echo "Hello from mac node"
clawdis nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway ready"
clawdbot nodes run --node <idOrNameOrIp> -- echo "Hello from mac node"
clawdbot nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway ready"
```
Notes:
@@ -145,7 +145,7 @@ Nodes may include a `permissions` map in `node.list` / `node.describe`, keyed by
## Mac node mode
- The macOS menubar app connects to the Gateway bridge as a node (so `clawdis nodes …` works against this Mac).
- The macOS menubar app connects to the Gateway bridge as a node (so `clawdbot nodes …` works against this Mac).
- In remote mode, the app opens an SSH tunnel for the bridge port and connects to `localhost`.
## Where to look in code
@@ -154,4 +154,4 @@ Nodes may include a `permissions` map in `node.list` / `node.describe`, keyed by
- Canvas snapshot decoding/temp paths: `src/cli/nodes-canvas.ts`
- Duration parsing for CLI: `src/cli/parse-duration.ts`
- iOS node commands: `apps/ios/Sources/Model/NodeAppModel.swift`
- Android node commands: `apps/android/app/src/main/java/com/steipete/clawdis/node/node/*`
- Android node commands: `apps/android/app/src/main/java/com/clawdbot/android/node/*`
docs/onboarding.md
+23 -23
View File
@@ -1,5 +1,5 @@
---
summary: "Planned first-run onboarding flow for Clawdis (local vs remote, Anthropic OAuth, workspace bootstrap ritual)"
summary: "Planned first-run onboarding flow for Clawdbot (local vs remote, Anthropic OAuth, workspace bootstrap ritual)"
read_when:
- Designing the macOS onboarding assistant
- Implementing Anthropic auth or identity setup
@@ -7,31 +7,31 @@ read_when:
<!-- {% raw %} -->
# Onboarding (macOS app)
This doc describes the intended **first-run onboarding** for Clawdis. The goal is a good “day 0” experience: pick where the Gateway runs, bind Claude (Anthropic) auth for the embedded agent runtime, and then let the **agent bootstrap itself** via a first-run ritual in the workspace.
This doc describes the intended **first-run onboarding** for Clawdbot. The goal is a good “day 0” experience: pick where the Gateway runs, bind Claude (Anthropic) auth for the embedded agent runtime, and then let the **agent bootstrap itself** via a first-run ritual in the workspace.
## Page order (high level)
1) **Local vs Remote**
2) **(Local only)** Connect Claude (Anthropic OAuth) — optional, but recommended
3) **Connect Gmail (optional)** — run `clawdis hooks gmail setup` to configure Pub/Sub hooks
3) **Connect Gmail (optional)** — run `clawdbot hooks gmail setup` to configure Pub/Sub hooks
4) **Onboarding chat** — dedicated session where the agent introduces itself and guides setup
## 1) Local vs Remote
First question: where does the **Gateway** run?
- **Local (this Mac):** onboarding can run the Anthropic OAuth flow and write the Clawdis token store locally.
- **Local (this Mac):** onboarding can run the Anthropic OAuth flow and write the Clawdbot token store locally.
- **Remote (over SSH/tailnet):** onboarding must not run OAuth locally, because credentials must exist on the **gateway host**.
Gateway auth tip:
- If you only use Clawdis on this Mac (loopback gateway), keep auth **Off**.
- If you only use Clawdbot on this Mac (loopback gateway), keep auth **Off**.
- Use **Token** for multi-machine access or non-loopback binds.
Implementation note (2025-12-19): in local mode, the macOS app bundles the Gateway and enables it via a per-user launchd LaunchAgent (no global npm install/Node requirement for the user).
## 2) Local-only: Connect Claude (Anthropic OAuth)
This is the “bind Clawdis to Anthropic” step. It is explicitly the **Anthropic (Claude Pro/Max) OAuth flow**, not a generic “login”.
This is the “bind Clawdbot to Anthropic” step. It is explicitly the **Anthropic (Claude Pro/Max) OAuth flow**, not a generic “login”.
### Recommended: OAuth
@@ -39,27 +39,27 @@ The macOS app should:
- Start the Anthropic OAuth (PKCE) flow in the user’s browser.
- Ask the user to paste the `code#state` value.
- Exchange it for tokens and write credentials to:
- `~/.clawdis/credentials/oauth.json` (file mode `0600`, directory mode `0700`)
- `~/.clawdbot/credentials/oauth.json` (file mode `0600`, directory mode `0700`)
Why this location matters: it’s the Clawdis-owned OAuth store.
On first run, Clawdis can import existing OAuth tokens from legacy p/Claude locations if present.
Why this location matters: it’s the Clawdbot-owned OAuth store.
On first run, Clawdbot can import existing OAuth tokens from legacy p/Claude locations if present.
### Alternative: API key (instructions only)
Offer an “API key” option, but for now it is **instructions only**:
- Get an Anthropic API key.
- Provide it to Clawdis via your preferred mechanism (env/config).
- Provide it to Clawdbot via your preferred mechanism (env/config).
Note: environment variables are often confusing when the Gateway is launched by a GUI app (launchd environment != your shell).
### Model safety rule
Clawdis should **always pass** `--model` when invoking the embedded agent (don’t rely on defaults).
Clawdbot should **always pass** `--model` when invoking the embedded agent (don’t rely on defaults).
Example (CLI):
```bash
clawdis agent --mode rpc --model anthropic/claude-opus-4-5 "<message>"
clawdbot agent --mode rpc --model anthropic/claude-opus-4-5 "<message>"
```
If the user skips auth, onboarding should be clear: the agent likely won’t respond until auth is configured.
@@ -82,7 +82,7 @@ If the workspace bootstrap is already complete (BOOTSTRAP.md removed), the onboa
The macOS onboarding includes an optional Gmail step. It runs:
```bash
clawdis hooks gmail setup --account you@gmail.com
clawdbot hooks gmail setup --account you@gmail.com
```
This writes the full `hooks.gmail` config, installs `gcloud` / `gog` / `tailscale`
@@ -95,7 +95,7 @@ Once setup is complete, the user can switch to the normal chat (`main`) via the
We no longer collect identity in the onboarding wizard. Instead, the **first agent run** performs a playful bootstrap ritual using files in the workspace:
- Workspace is created implicitly (default `~/.clawdis/workspace`) when local is selected,
- Workspace is created implicitly (default `~/.clawdbot/workspace`) when local is selected,
but only if the folder is empty or already contains `AGENTS.md`.
- Files are seeded: `AGENTS.md`, `BOOTSTRAP.md`, `IDENTITY.md`, `USER.md`.
- `BOOTSTRAP.md` tells the agent to keep it conversational:
@@ -107,7 +107,7 @@ We no longer collect identity in the onboarding wizard. Instead, the **first age
- `IDENTITY.md` (agent name, vibe/creature, emoji)
- `USER.md` (who the user is + how they want to be addressed)
- `SOUL.md` (identity, tone, boundaries — crafted from the soul.md prompt)
- `~/.clawdis/clawdis.json` (structured identity defaults)
- `~/.clawdbot/clawdbot.json` (structured identity defaults)
- After the ritual, the agent **deletes `BOOTSTRAP.md`** so it only runs once.
Identity data still feeds the same defaults as before:
@@ -124,7 +124,7 @@ The workspace is created automatically as part of agent bootstrap (no dedicated
Recommendation: treat the workspace as the agent’s “memory” and make it a git repo (ideally private) so identity + memories are backed up:
```bash
cd ~/.clawdis/workspace
cd ~/.clawdbot/workspace
git init
git add AGENTS.md
git commit -m "Add agent workspace"
@@ -141,12 +141,12 @@ If the Gateway runs on another machine, the Anthropic OAuth credentials must be
For now, remote onboarding should:
- explain why OAuth isn't shown
- point the user at the credential location (`~/.clawdis/credentials/oauth.json`) and the workspace location on the gateway host
- point the user at the credential location (`~/.clawdbot/credentials/oauth.json`) and the workspace location on the gateway host
- mention that the **bootstrap ritual happens on the gateway host** (same BOOTSTRAP/IDENTITY/USER files)
### Manual credential setup
On the gateway host, create `~/.clawdis/credentials/oauth.json` with this exact format:
On the gateway host, create `~/.clawdbot/credentials/oauth.json` with this exact format:
```json
{
@@ -158,9 +158,9 @@ On the gateway host, create `~/.clawdis/credentials/oauth.json` with this exact
}
```
Set permissions: `chmod 600 ~/.clawdis/credentials/oauth.json`
Set permissions: `chmod 600 ~/.clawdbot/credentials/oauth.json`
**Note:** Clawdis can auto-import from legacy pi-coding-agent paths (`~/.pi/agent/oauth.json`, etc.) but this does NOT work with Claude Code credentials — different file and format.
**Note:** Clawdbot can auto-import from legacy pi-coding-agent paths (`~/.pi/agent/oauth.json`, etc.) but this does NOT work with Claude Code credentials — different file and format.
### Using Claude Code credentials
@@ -173,11 +173,11 @@ cat ~/.claude/.credentials.json | jq '{
refresh: .claudeAiOauth.refreshToken,
expires: .claudeAiOauth.expiresAt
}
}' > ~/.clawdis/credentials/oauth.json
chmod 600 ~/.clawdis/credentials/oauth.json
}' > ~/.clawdbot/credentials/oauth.json
chmod 600 ~/.clawdbot/credentials/oauth.json
```
| Claude Code field | Clawdis field |
| Claude Code field | Clawdbot field |
|-------------------|---------------|
| `accessToken` | `access` |
| `refreshToken` | `refresh` |
docs/presence.md
+6 -6
View File
@@ -1,5 +1,5 @@
---
summary: "How Clawdis presence entries are produced, merged, and displayed"
summary: "How Clawdbot presence entries are produced, merged, and displayed"
read_when:
- Debugging the Instances tab
- Investigating duplicate or stale instance rows
@@ -7,7 +7,7 @@ read_when:
---
# Presence
Clawdis “presence” is a lightweight, best-effort view of:
Clawdbot “presence” is a lightweight, best-effort view of:
- The **Gateway** itself (one per host), and
- The **clients connected to the Gateway** (mac app, WebChat, CLI, etc.).
@@ -59,7 +59,7 @@ Clients can publish richer periodic beacons via the `system-event` method. The m
Implementation:
- Gateway: `src/gateway/server.ts` handles method `system-event` by calling `updateSystemPresence(...)`.
- mac app beaconing: `apps/macos/Sources/Clawdis/PresenceReporter.swift`.
- mac app beaconing: `apps/macos/Sources/Clawdbot/PresenceReporter.swift`.
### 4) Node bridge beacons (gateway-owned presence)
@@ -89,7 +89,7 @@ The mac app uses a persisted UUID as `instanceId` so:
- renaming the Mac does not create a new “instance”
- debug/release builds can share the same identity
Implementation: `apps/macos/Sources/Clawdis/InstanceIdentity.swift`.
Implementation: `apps/macos/Sources/Clawdbot/InstanceIdentity.swift`.
`displayName` (machine name) is used for UI, while `instanceId` is used for dedupe.
@@ -116,8 +116,8 @@ Implementation: `src/gateway/server.ts` (`isLoopbackAddress()`).
The mac app’s Instances tab renders the result of `system-presence`.
Implementation:
- View: `apps/macos/Sources/Clawdis/InstancesSettings.swift`
- Store: `apps/macos/Sources/Clawdis/InstancesStore.swift`
- View: `apps/macos/Sources/Clawdbot/InstancesSettings.swift`
- Store: `apps/macos/Sources/Clawdbot/InstancesStore.swift`
The Instances rows show a small presence indicator (Active/Idle/Stale) based on
the last beacon age. The label is derived from the entry timestamp (`ts`).
docs/refactor/canvas-a2ui.md
+8 -8
View File
@@ -41,11 +41,11 @@ Add A2UI HTML/JS to the Gateway Canvas host (standalone HTTP server on
`canvasHost.port`), e.g.:
```
/__clawdis__/a2ui/ -> index.html
/__clawdis__/a2ui/a2ui.bundle.js -> bundled A2UI runtime
/__clawdbot__/a2ui/ -> index.html
/__clawdbot__/a2ui/a2ui.bundle.js -> bundled A2UI runtime
```
Serve Canvas files at `/__clawdis__/canvas/` and A2UI at `/__clawdis__/a2ui/`.
Serve Canvas files at `/__clawdbot__/canvas/` and A2UI at `/__clawdbot__/a2ui/`.
Use the shared Canvas host handler (`src/canvas-host/server.ts`) to serve these
assets and inject the action bridge + live reload if desired.
@@ -57,11 +57,11 @@ so nodes don’t need to guess.
### Navigation path
Before applying A2UI:
- Navigate to `${canvasHostUrl}/__clawdis__/a2ui/`.
- Navigate to `${canvasHostUrl}/__clawdbot__/a2ui/`.
### Remove bundled shells
Remove all fallback logic that serves A2UI from local bundles:
- macOS: remove custom-scheme fallback for `/__clawdis__/a2ui/`
- macOS: remove custom-scheme fallback for `/__clawdbot__/a2ui/`
- iOS/Android: remove packaged A2UI assets and "default scaffold" assumptions
### Error behavior
@@ -76,14 +76,14 @@ If `canvasHostUrl` is missing or unreachable:
## Implementation plan
1) Gateway
- Add A2UI assets under `src/canvas-host/`.
- Serve them at `/__clawdis__/a2ui/` (align with existing naming).
- Serve Canvas files at `/__clawdis__/canvas/` on `canvasHost.port`.
- Serve them at `/__clawdbot__/a2ui/` (align with existing naming).
- Serve Canvas files at `/__clawdbot__/canvas/` on `canvasHost.port`.
- Expose `canvasHostUrl` in handshake + bridge hello payloads.
2) Node runtimes
- Update `canvas.a2ui.*` to navigate to `canvasHostUrl`.
- Remove custom-scheme A2UI fallback and bundled assets.
3) Tests
- TS: verify `/__clawdis__/a2ui/` responds with HTML + JS.
- TS: verify `/__clawdbot__/a2ui/` responds with HTML + JS.
- Node: verify A2UI fails when host is unreachable and succeeds when reachable.
4) Docs
- Update `docs/mac/canvas.md`, `docs/ios/spec.md`, `docs/android/connect.md`
docs/refactor/cli-unification.md
+14 -14
View File
@@ -1,23 +1,23 @@
---
summary: "Refactor: unify on the clawdis CLI + gateway-first control; retire clawdis-mac"
summary: "Refactor: unify on the clawdbot CLI + gateway-first control; retire clawdbot-mac"
read_when:
- Removing or replacing the macOS CLI helper
- Adding node capabilities or permissions metadata
- Updating macOS app packaging/install flows
---
# CLI unification (clawdis-only)
# CLI unification (clawdbot-only)
Status: active refactor · Date: 2025-12-20
## Goals
- **Single CLI**: use `clawdis` for all automation (local + remote). Retire `clawdis-mac`.
- **Single CLI**: use `clawdbot` for all automation (local + remote). Retire `clawdbot-mac`.
- **Gateway-first**: all agent actions flow through the Gateway WebSocket + node.invoke.
- **Permission awareness**: nodes advertise permission state so the agent can decide what to run.
- **No duplicate paths**: remove macOS control socket + Swift CLI surface.
## Non-goals
- Keep legacy `clawdis-mac` compatibility.
- Keep legacy `clawdbot-mac` compatibility.
- Support agent control when no Gateway is running.
## Key decisions
@@ -29,19 +29,19 @@ Status: active refactor · Date: 2025-12-20
- Permissions are **advertised by the node** (e.g., screen recording granted/denied).
- Commands will still fail with explicit errors when permissions are missing.
3) **Mac app installs/symlinks `clawdis`**
- Bundle a standalone `clawdis` binary in the app (bun-compiled).
- Install/symlink that binary to `/usr/local/bin/clawdis` and `/opt/homebrew/bin/clawdis`.
- No `clawdis-mac` helper remains.
3) **Mac app installs/symlinks `clawdbot`**
- Bundle a standalone `clawdbot` binary in the app (bun-compiled).
- Install/symlink that binary to `/usr/local/bin/clawdbot` and `/opt/homebrew/bin/clawdbot`.
- No `clawdbot-mac` helper remains.
4) **Canvas parity across node types**
- Use `node.invoke` commands consistently (`canvas.present|navigate|eval|snapshot|a2ui.*`).
- The TS CLI provides convenient wrappers so agents never have to craft raw `node.invoke` calls.
## Command surface (new/normalized)
- `clawdis nodes invoke --command canvas.*` remains valid.
- `clawdbot nodes invoke --command canvas.*` remains valid.
- New CLI wrappers for convenience:
- `clawdis canvas present|navigate|eval|snapshot|a2ui push|a2ui reset`
- `clawdbot canvas present|navigate|eval|snapshot|a2ui push|a2ui reset`
- New node commands (mac-only initially):
- `system.run` (shell execution)
- `system.notify` (local notifications)
@@ -54,11 +54,11 @@ Status: active refactor · Date: 2025-12-20
## Gateway mode + config
- Gateways should only auto-start when explicitly configured for **local** mode.
- When config is missing or explicitly remote, `clawdis gateway` should refuse to auto-start unless forced.
- When config is missing or explicitly remote, `clawdbot gateway` should refuse to auto-start unless forced.
## Implementation checklist
- Add bun-compiled `clawdis` binary to macOS app bundle; update codesign + install flows.
- Remove `ClawdisCLI` target and control socket server.
- Add bun-compiled `clawdbot` binary to macOS app bundle; update codesign + install flows.
- Remove `ClawdbotCLI` target and control socket server.
- Add node command(s) for `system.run` and `system.notify` on macOS.
- Add permission map to node hello/pairing + gateway responses.
- Update TS CLI + docs to use `clawdis` only.
- Update TS CLI + docs to use `clawdbot` only.
docs/refactor/new-arch.md
+6 -6
View File
@@ -12,12 +12,12 @@ Goal: replace legacy gateway/stdin/TCP control with a single WebSocket Gateway,
---
## Phase 0 — Foundations
- **Naming**: CLI subcommand `clawdis gateway`; internal namespace `Gateway`.
- **Naming**: CLI subcommand `clawdbot gateway`; internal namespace `Gateway`.
- **Protocol folder**: create `protocol/` for schemas and build artifacts. ✅ `src/gateway/protocol`.
- **Schema tooling**:
- Prefer **TypeBox** (or ArkType) as source-of-truth types. ✅ TypeBox in `schema.ts`.
- `pnpm protocol:gen`: emits JSON Schema (`dist/protocol.schema.json`). ✅
- `pnpm protocol:gen:swift`: generates Swift `Codable` models (`apps/macos/Sources/ClawdisProtocol/GatewayModels.swift`). ✅
- `pnpm protocol:gen:swift`: generates Swift `Codable` models (`apps/macos/Sources/ClawdbotProtocol/GatewayModels.swift`). ✅
- AJV compile step for server validators. ✅
- **CI**: add a job that fails if schema or generated Swift is stale. ✅ `pnpm protocol:check` (runs gen + git diff).
@@ -32,7 +32,7 @@ Goal: replace legacy gateway/stdin/TCP control with a single WebSocket Gateway,
- `close` (standard WS close codes; policy uses 1008 for slow consumer/unauthorized, 1012/1001 for restart)
- Payload types:
- `PresenceEntry {host, ip, version, platform?, deviceFamily?, modelIdentifier?, mode, lastInputSeconds?, ts, reason?, tags?[], instanceId?}`
- `HealthSnapshot` (match existing `clawdis health --json` fields)
- `HealthSnapshot` (match existing `clawdbot health --json` fields)
- `AgentEvent` (streamed tool/output; `{runId, seq, stream, data, ts}`)
- `TickEvent {ts}`
- `ShutdownEvent {reason, restartExpectedMs?}`
@@ -77,7 +77,7 @@ Goal: replace legacy gateway/stdin/TCP control with a single WebSocket Gateway,
- Dedupe cache: bound TTL (~5m) and max size (~1000 entries); evict oldest first (LRU) to prevent memory growth.
## Phase 3 — Gateway CLI entrypoint
- Add `clawdis gateway` command in CLI program:
- Add `clawdbot gateway` command in CLI program:
- Reads config (port, WS options).
- Foreground process; exit non-zero on fatal errors.
- Flags: `--port`, `--no-tick` (optional), `--log-json` (optional).
@@ -124,7 +124,7 @@ Goal: replace legacy gateway/stdin/TCP control with a single WebSocket Gateway,
- Include `policy` in `hello-ok` so clients know the tick interval and buffer limits to tune their expectations.
## Phase 8 — Cleanup and deprecation
- Retire `clawdis rpc` as default path; keep only if explicitly requested (documented as legacy).
- Retire `clawdbot rpc` as default path; keep only if explicitly requested (documented as legacy).
- Remove reliance on `src/infra/control-channel.ts` for new clients; mark as legacy or delete after migration. ✅ file removed; mac app now uses Gateway WS.
- Update README, docs (`architecture.md`, `gateway.md`, `webchat.md`) to final shapes; remove `control-api.md` references if obsolete.
- Presence hygiene:
@@ -152,7 +152,7 @@ Goal: replace legacy gateway/stdin/TCP control with a single WebSocket Gateway,
## Phase 10 — Rollout
- Version bump; release notes: breaking change to control plane (WS only).
- Ship launchd/systemd templates for `clawdis gateway`.
- Ship launchd/systemd templates for `clawdbot gateway`.
- Recommend Tailscale/SSH tunnel for remote access; no additional auth layer assumed in this model.
---
docs/refactor/tui.md
+3 -3
View File
@@ -2,7 +2,7 @@
summary: "Refactor plan: Gateway TUI parity with pi-mono interactive UI"
read_when:
- Building or refactoring the Gateway TUI
- Syncing TUI slash commands with Clawdis behavior
- Syncing TUI slash commands with Clawdbot behavior
---
# Gateway TUI refactor plan
@@ -10,7 +10,7 @@ Updated: 2026-01-03
## Goals
- Match pi-mono interactive TUI feel (editor, streaming, tool cards, selectors).
- Keep Clawdis semantics: Gateway WS only, session store owns state, no branching/export.
- Keep Clawdbot semantics: Gateway WS only, session store owns state, no branching/export.
- Work locally or remotely via Gateway URL/token.
## Non-goals
@@ -21,6 +21,6 @@ Updated: 2026-01-03
- [x] Protocol + server: sessions.patch supports model overrides; agent events include tool results (text-only payloads).
- [x] Gateway TUI client: add session/model helpers + stricter typing.
- [x] TUI UI kit: theme + components (editor, message feed, tool cards, selectors).
- [x] TUI controller: keybindings + Clawdis slash commands + history/stream wiring.
- [x] TUI controller: keybindings + Clawdbot slash commands + history/stream wiring.
- [x] Docs + changelog updated for the new TUI behavior.
- [x] Gate: lint, build, tests, docs list.
docs/refactor/web-gateway-troubleshooting.md
+7 -7
View File
@@ -6,18 +6,18 @@ read_when:
# Web Gateway Troubleshooting (Nov 26, 2025)
## Symptoms & quick fixes
- **Stream Errored / Conflict / status 409–515:** WhatsApp closed the socket because another session is active or creds went stale. Run `clawdis logout`, then `clawdis login`, then restart the Gateway.
- **Logged out:** Console prints “session logged out”; re-link with `clawdis login`.
- **Stream Errored / Conflict / status 409–515:** WhatsApp closed the socket because another session is active or creds went stale. Run `clawdbot logout`, then `clawdbot login`, then restart the Gateway.
- **Logged out:** Console prints “session logged out”; re-link with `clawdbot login`.
- **Repeated retries then exit:** Tune reconnect behavior via config `web.reconnect` and restart the Gateway.
- **No inbound messages:** Ensure the QR-linked account is online in WhatsApp, and check logs for `web-heartbeat` to confirm auth age/connection.
- **Status 515 right after pairing:** The QR login flow now auto-restarts once; you should not need a manual gateway restart after scanning.
- **Fast nuke:** From an allowed WhatsApp sender you can send `/restart` to request a supervised restart (launchd/mac app setups); wait a few seconds for it to come back.
## Helpful commands
- Start the Gateway: `clawdis gateway --verbose`
- Logout (clear creds): `clawdis logout`
- Relink (show QR): `clawdis login --verbose`
- Tail logs (default): `tail -f /tmp/clawdis/clawdis-*.log`
- Start the Gateway: `clawdbot gateway --verbose`
- Logout (clear creds): `clawdbot logout`
- Relink (show QR): `clawdbot login --verbose`
- Tail logs (default): `tail -f /tmp/clawdbot/clawdbot-*.log`
## Reading the logs
- `web-reconnect`: close reasons, retry/backoff, max-attempt exit.
@@ -30,7 +30,7 @@ read_when:
- Chatty monitors: increase `web.heartbeatSeconds` if log volume is high.
## If it keeps failing
1) `clawdis logout` → `clawdis login` (fresh QR link).
1) `clawdbot logout` → `clawdbot login` (fresh QR link).
2) Ensure no other device/browser is using the same WA Web session.
3) Check WhatsApp mobile app is online and not in low-power mode.
4) If status is 515, let the client restart once after pairing (already handled automatically).
docs/refactor/webagent-session.md
+1 -1
View File
@@ -31,7 +31,7 @@ Context: web chat currently lives in a WKWebView that loads the pi-web bundle. S
- Remove reliance on session file snapshots and `/rpc`.
## Persistence
- Keep passing `--session <.../.clawdis/sessions/{{SessionId}}.jsonl>` to Pi so it continues writing JSONL. The WS history reader uses the same file; no new store introduced.
- Keep passing `--session <.../.clawdbot/sessions/{{SessionId}}.jsonl>` to Pi so it continues writing JSONL. The WS history reader uses the same file; no new store introduced.
## Docs to update when shipping
- `docs/webchat.md` (WS-only flow, methods/events, health gate, tunnel WS port).
docs/remote-gateway-readme.md
+13 -13
View File
@@ -1,6 +1,6 @@
# Running Clawdis.app with a Remote Gateway
# Running Clawdbot.app with a Remote Gateway
Clawdis.app uses SSH tunneling to connect to a remote gateway. This guide shows you how to set it up.
Clawdbot.app uses SSH tunneling to connect to a remote gateway. This guide shows you how to set it up.
## Overview
@@ -8,7 +8,7 @@ Clawdis.app uses SSH tunneling to connect to a remote gateway. This guide shows
┌─────────────────────────────────────────────────────────────┐
│ MacBook │
│ │
│ Clawdis.app ──► ws://127.0.0.1:18789 (local port) │
│ Clawdbot.app ──► ws://127.0.0.1:18789 (local port) │
│ │ │
│ ▼ │
│ SSH Tunnel ────────────────────────────────────────────────│
@@ -51,7 +51,7 @@ ssh-copy-id -i ~/.ssh/id_rsa <REMOTE_USER>@<REMOTE_IP>
### Step 3: Set Gateway Token
```bash
launchctl setenv CLAWDIS_GATEWAY_TOKEN "<your-token>"
launchctl setenv CLAWDBOT_GATEWAY_TOKEN "<your-token>"
```
### Step 4: Start SSH Tunnel
@@ -60,11 +60,11 @@ launchctl setenv CLAWDIS_GATEWAY_TOKEN "<your-token>"
ssh -N remote-gateway &
```
### Step 5: Restart Clawdis.app
### Step 5: Restart Clawdbot.app
```bash
killall Clawdis
open /path/to/Clawdis.app
killall Clawdbot
open /path/to/Clawdbot.app
```
The app will now connect to the remote gateway through the SSH tunnel.
@@ -77,7 +77,7 @@ To have the SSH tunnel start automatically when you log in, create a Launch Agen
### Create the PLIST file
Save this as `~/Library/LaunchAgents/com.clawdis.ssh-tunnel.plist`:
Save this as `~/Library/LaunchAgents/com.clawdbot.ssh-tunnel.plist`:
```xml
<?xml version="1.0" encoding="UTF-8"?>
@@ -85,7 +85,7 @@ Save this as `~/Library/LaunchAgents/com.clawdis.ssh-tunnel.plist`:
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.clawdis.ssh-tunnel</string>
<string>com.clawdbot.ssh-tunnel</string>
<key>ProgramArguments</key>
<array>
<string>/usr/bin/ssh</string>
@@ -103,7 +103,7 @@ Save this as `~/Library/LaunchAgents/com.clawdis.ssh-tunnel.plist`:
### Load the Launch Agent
```bash
launchctl load ~/Library/LaunchAgents/com.clawdis.ssh-tunnel.plist
launchctl load ~/Library/LaunchAgents/com.clawdbot.ssh-tunnel.plist
```
The tunnel will now:
@@ -125,13 +125,13 @@ lsof -i :18789
**Restart the tunnel:**
```bash
launchctl restart com.clawdis.ssh-tunnel
launchctl restart com.clawdbot.ssh-tunnel
```
**Stop the tunnel:**
```bash
launchctl unload ~/Library/LaunchAgents/com.clawdis.ssh-tunnel.plist
launchctl unload ~/Library/LaunchAgents/com.clawdbot.ssh-tunnel.plist
```
---
@@ -145,4 +145,4 @@ launchctl unload ~/Library/LaunchAgents/com.clawdis.ssh-tunnel.plist
| `KeepAlive` | Automatically restarts tunnel if it crashes |
| `RunAtLoad` | Starts tunnel when the agent loads |
Clawdis.app connects to `ws://127.0.0.1:18789` on your MacBook. The SSH tunnel forwards that connection to port 18789 on the remote machine where the Gateway is running.
Clawdbot.app connects to `ws://127.0.0.1:18789` on your MacBook. The SSH tunnel forwards that connection to port 18789 on the remote machine where the Gateway is running.
docs/remote.md
+3 -3
View File
@@ -24,10 +24,10 @@ ssh -N -L 18789:127.0.0.1:18789 user@host
```
With the tunnel up:
- `clawdis health` and `clawdis status --deep` now reach the remote gateway via `ws://127.0.0.1:18789`.
- `clawdis gateway {status,health,send,agent,call}` can also target the forwarded URL via `--url` when needed.
- `clawdbot health` and `clawdbot status --deep` now reach the remote gateway via `ws://127.0.0.1:18789`.
- `clawdbot gateway {status,health,send,agent,call}` can also target the forwarded URL via `--url` when needed.
Note: replace `18789` with your configured `gateway.port` (or `--port`/`CLAWDIS_GATEWAY_PORT`).
Note: replace `18789` with your configured `gateway.port` (or `--port`/`CLAWDBOT_GATEWAY_PORT`).
## CLI remote defaults
docs/research/memory.md
+7 -7
View File
@@ -2,7 +2,7 @@
summary: "Proposal + research notes: offline memory system for Clawd workspaces (Markdown source-of-truth + derived index)"
read_when:
- Designing workspace memory (~/clawd) beyond daily Markdown logs
- Deciding: standalone CLI vs deep Clawdis integration
- Deciding: standalone CLI vs deep Clawdbot integration
- Adding offline recall + reflection (retain/recall/reflect)
---
@@ -155,16 +155,16 @@ Opinion evolution (simple, explainable):
## CLI integration: standalone vs deep integration
Recommendation: **deep integration in Clawdis**, but keep a separable core library.
Recommendation: **deep integration in Clawdbot**, but keep a separable core library.
### Why integrate into Clawdis?
- Clawdis already knows:
### Why integrate into Clawdbot?
- Clawdbot already knows:
- the workspace path (`agent.workspace`)
- the session model + heartbeats
- logging + troubleshooting patterns
- You want the agent itself to call the tools:
- `clawdis memory recall "…" --k 25 --since 30d`
- `clawdis memory reflect --since 7d`
- `clawdbot memory recall "…" --k 25 --since 30d`
- `clawdbot memory reflect --since 7d`
### Why still split a library?
- keep memory logic testable without gateway/runtime
@@ -202,7 +202,7 @@ Open question:
- add `bank/` files + entity pages
- add `## Retain` convention to daily logs
### Phase 1: `clawdis memory index|recall` (FTS-only)
### Phase 1: `clawdbot memory index|recall` (FTS-only)
- parse Markdown (`memory/*.md`, `bank/*.md`) into chunks
- write to SQLite: `facts`, `entities`, `fact_entities`, `opinions`
- FTS5 table over `facts.content`
docs/rpc.md
+3 -3
View File
@@ -6,18 +6,18 @@ read_when:
---
# RPC adapters
Clawdis integrates external CLIs via JSON-RPC. Two patterns are used today.
Clawdbot integrates external CLIs via JSON-RPC. Two patterns are used today.
## Pattern A: HTTP daemon (signal-cli)
- `signal-cli` runs as a daemon with JSON-RPC over HTTP.
- Event stream is SSE (`/api/v1/events`).
- Health probe: `/api/v1/check`.
- Clawdis owns lifecycle when `signal.autoStart=true`.
- Clawdbot owns lifecycle when `signal.autoStart=true`.
See `docs/signal.md` for setup and endpoints.
## Pattern B: stdio child process (imsg)
- Clawdis spawns `imsg rpc` as a child process.
- Clawdbot spawns `imsg rpc` as a child process.
- JSON-RPC is line-delimited over stdin/stdout (one JSON object per line).
- No TCP port, no daemon required.
docs/security.md
+10 -10
View File
@@ -84,24 +84,24 @@ We're considering a `readOnlyMode` flag that prevents the AI from:
## Container Isolation (Recommended)
For maximum security, run CLAWDIS in a container with limited access:
For maximum security, run CLAWDBOT in a container with limited access:
```yaml
# docker-compose.yml
services:
clawdis:
clawdbot:
build: .
volumes:
- ./clawd-sandbox:/home/clawd # Limited filesystem
- /tmp/clawdis:/tmp/clawdis # Logs
- /tmp/clawdbot:/tmp/clawdbot # Logs
environment:
- CLAWDIS_SANDBOX=true
- CLAWDBOT_SANDBOX=true
network_mode: bridge # Limited network
```
### Per-session sandbox (Clawdis-native)
### Per-session sandbox (Clawdbot-native)
Clawdis can also run **non-main sessions** inside per-session Docker containers
Clawdbot can also run **non-main sessions** inside per-session Docker containers
(`agent.sandbox`). This keeps the gateway on your host while isolating agent
tools in a hard wall container. See `docs/configuration.md` for the full config.
@@ -128,9 +128,9 @@ Include security guidelines in your agent's system prompt:
If your AI does something bad:
1. **Stop it:** stop the macOS app (if it’s supervising the Gateway) or terminate your `clawdis gateway` process
2. **Check logs:** `/tmp/clawdis/clawdis-YYYY-MM-DD.log` (or your configured `logging.file`)
3. **Review session:** Check `~/.clawdis/sessions/` for what happened
1. **Stop it:** stop the macOS app (if it’s supervising the Gateway) or terminate your `clawdbot gateway` process
2. **Check logs:** `/tmp/clawdbot/clawdbot-YYYY-MM-DD.log` (or your configured `logging.file`)
3. **Review session:** Check `~/.clawdbot/sessions/` for what happened
4. **Rotate secrets:** If credentials were exposed
5. **Update rules:** Add to your security prompt
@@ -155,7 +155,7 @@ Mario asking for find ~
## Reporting Security Issues
Found a vulnerability in CLAWDIS? Please report responsibly:
Found a vulnerability in CLAWDBOT? Please report responsibly:
1. Email: security@[redacted].com
2. Don't post publicly until fixed
docs/session-tool.md
+2 -2
View File
@@ -76,11 +76,11 @@ Behavior:
- If the run fails: `{ runId, status: "error", error }`.
- Waits via gateway `agent.wait` (server-side) so reconnects don't drop the wait.
- Agent-to-agent message context is injected for the primary run.
- After the primary run completes, Clawdis runs a **reply-back loop**:
- After the primary run completes, Clawdbot runs a **reply-back loop**:
- Round 2+ alternates between requester and target agents.
- Reply exactly `REPLY_SKIP` to stop the ping‑pong.
- Max turns is `session.agentToAgent.maxPingPongTurns` (0–5, default 5).
- Once the loop ends, Clawdis runs the **agent‑to‑agent announce step** (target agent only):
- Once the loop ends, Clawdbot runs the **agent‑to‑agent announce step** (target agent only):
- Reply exactly `ANNOUNCE_SKIP` to stay silent.
- Any other reply is sent to the target channel.
- Announce step includes the original request + round‑1 reply + latest ping‑pong reply.
docs/session.md
+11 -11
View File
@@ -5,21 +5,21 @@ read_when:
---
# Session Management
Clawdis treats **one session as primary**. The canonical key is fixed to `main` for direct chats (or `global` when scope is global); no configuration is required. `session.mainKey` is ignored. Older/local sessions can stay on disk, but only the primary key is used for desktop/web chat and direct agent calls.
Clawdbot treats **one session as primary**. The canonical key is fixed to `main` for direct chats (or `global` when scope is global); no configuration is required. `session.mainKey` is ignored. Older/local sessions can stay on disk, but only the primary key is used for desktop/web chat and direct agent calls.
## Gateway is the source of truth
All session state is **owned by the gateway** (the “master” Clawdis). UI clients (macOS app, WebChat, etc.) must query the gateway for session lists and token counts instead of reading local files.
All session state is **owned by the gateway** (the “master” Clawdbot). UI clients (macOS app, WebChat, etc.) must query the gateway for session lists and token counts instead of reading local files.
- In **remote mode**, the session store you care about lives on the remote gateway host, not your Mac.
- Token counts shown in UIs come from the gateway’s store fields (`inputTokens`, `outputTokens`, `totalTokens`, `contextTokens`). Clients do not parse JSONL transcripts to “fix up” totals.
## Where state lives
- On the **gateway host**:
- Store file: `~/.clawdis/sessions/sessions.json` (legacy: `~/.clawdis/sessions.json`).
- Transcripts: `~/.clawdis/sessions/<SessionId>.jsonl` (one file per session id).
- Store file: `~/.clawdbot/sessions/sessions.json` (legacy: `~/.clawdbot/sessions.json`).
- Transcripts: `~/.clawdbot/sessions/<SessionId>.jsonl` (one file per session id).
- The store is a map `sessionKey -> { sessionId, updatedAt, ... }`. Deleting entries is safe; they are recreated on demand.
- Group entries may include `displayName`, `surface`, `subject`, `room`, and `space` to label sessions in UIs.
- Clawdis does **not** read legacy Pi/Tau session folders.
- Clawdbot does **not** read legacy Pi/Tau session folders.
## Mapping transports → session keys
- Direct chats (WhatsApp, Telegram, Discord, desktop Web Chat) all collapse to the **primary key** so they share context.
@@ -33,7 +33,7 @@ All session state is **owned by the gateway** (the “master” Clawdis). UI cli
## Lifecyle
- Idle expiry: `session.idleMinutes` (default 60). After the timeout a new `sessionId` is minted on the next message.
- Reset triggers: exact `/new` or `/reset` (plus any extras in `resetTriggers`) start a fresh session id and pass the remainder of the message through. If `/new` or `/reset` is sent alone, Clawdis runs a short “hello” greeting turn to confirm the reset.
- Reset triggers: exact `/new` or `/reset` (plus any extras in `resetTriggers`) start a fresh session id and pass the remainder of the message through. If `/new` or `/reset` is sent alone, Clawdbot runs a short “hello” greeting turn to confirm the reset.
- Manual reset: delete specific keys from the store or remove the JSONL transcript; the next message recreates them.
## Send policy (optional)
@@ -60,22 +60,22 @@ Runtime override (owner only):
## Configuration (optional rename example)
```json5
// ~/.clawdis/clawdis.json
// ~/.clawdbot/clawdbot.json
{
session: {
scope: "per-sender", // keep group keys separate
idleMinutes: 120,
resetTriggers: ["/new", "/reset"],
store: "~/.clawdis/sessions/sessions.json",
store: "~/.clawdbot/sessions/sessions.json",
// mainKey is ignored; primary key is fixed to "main"
}
}
```
## Inspecting
- `pnpm clawdis status` — shows store path and recent sessions.
- `pnpm clawdis sessions --json` — dumps every entry (filter with `--active <minutes>`).
- `pnpm clawdis gateway call sessions.list --params '{}'` — fetch sessions from the running gateway (use `--url`/`--token` for remote gateway access).
- `pnpm clawdbot status` — shows store path and recent sessions.
- `pnpm clawdbot sessions --json` — dumps every entry (filter with `--active <minutes>`).
- `pnpm clawdbot gateway call sessions.list --params '{}'` — fetch sessions from the running gateway (use `--url`/`--token` for remote gateway access).
- Send `/status` in chat to see whether the agent is reachable, how much of the session context is used, current thinking/verbose toggles, and when your WhatsApp web creds were last refreshed (helps spot relink needs).
- JSONL transcripts can be opened directly to review full turns.
docs/setup.md
+15 -15
View File
@@ -1,5 +1,5 @@
---
summary: "Setup guide: keep your Clawdis setup tailored while staying up-to-date"
summary: "Setup guide: keep your Clawdbot setup tailored while staying up-to-date"
read_when:
- Setting up a new machine
- You want “latest + greatest” without breaking your personal setup
@@ -10,7 +10,7 @@ read_when:
Last updated: 2026-01-01
## TL;DR
- **Tailoring lives outside the repo:** `~/clawd` (workspace) + `~/.clawdis/clawdis.json` (config).
- **Tailoring lives outside the repo:** `~/clawd` (workspace) + `~/.clawdbot/clawdbot.json` (config).
- **Stable workflow:** install the macOS app; let it run the bundled Gateway.
- **Bleeding edge workflow:** run the Gateway yourself via `pnpm gateway:watch`, then point the macOS app at it using **Debug Settings → Gateway → Attach only**.
@@ -23,40 +23,40 @@ Last updated: 2026-01-01
If you want “100% tailored to me” *and* easy updates, keep your customization in:
- **Config:** `~/.clawdis/clawdis.json` (JSON/JSON5-ish)
- **Config:** `~/.clawdbot/clawdbot.json` (JSON/JSON5-ish)
- **Workspace:** `~/clawd` (skills, prompts, memories; make it a private git repo)
Bootstrap once:
```bash
clawdis setup
clawdbot setup
```
From inside this repo, use the local CLI entry:
```bash
pnpm clawdis setup
pnpm clawdbot setup
```
## Stable workflow (macOS app first)
1) Install + launch **Clawdis.app** (menu bar).
1) Install + launch **Clawdbot.app** (menu bar).
2) Complete the onboarding/permissions checklist (TCC prompts).
3) Ensure Gateway is **Local** and running (the app manages it).
4) Link surfaces (example: WhatsApp):
```bash
clawdis login
clawdbot login
```
5) Sanity check:
```bash
clawdis health
clawdbot health
```
If onboarding is still WIP/broken on your build:
- Run `clawdis setup`, then `clawdis login`, then start the Gateway manually (`clawdis gateway`).
- Run `clawdbot setup`, then `clawdbot login`, then start the Gateway manually (`clawdbot gateway`).
## Bleeding edge workflow (Gateway in a terminal)
@@ -81,7 +81,7 @@ pnpm gateway:watch
### 2) Point the macOS app at your running Gateway
In **Clawdis.app**:
In **Clawdbot.app**:
- Connection Mode: **Local**
- Settings → **Debug Settings** → **Gateway** → enable **Attach only**
@@ -94,19 +94,19 @@ This makes the app **only connect to an already-running gateway** and **never sp
- Or via CLI:
```bash
pnpm clawdis health
pnpm clawdbot health
```
### Common footguns
- **Attach only enabled, but nothing is running:** app shows “Attach-only enabled; no gateway to attach”.
- **Wrong port:** Gateway WS defaults to `ws://127.0.0.1:18789`; keep app + CLI on the same port.
- **Where state lives:**
- Credentials: `~/.clawdis/credentials/`
- Sessions/logs: `~/.clawdis/sessions/`
- Credentials: `~/.clawdbot/credentials/`
- Sessions/logs: `~/.clawdbot/sessions/`
## Updating (without wrecking your setup)
- Keep `~/clawd` and `~/.clawdis/` as “your stuff”; don’t put personal prompts/config into the `clawdis` repo.
- Keep `~/clawd` and `~/.clawdbot/` as “your stuff”; don’t put personal prompts/config into the `clawdbot` repo.
- Updating source: `git pull` + `pnpm install` (when lockfile changed) + keep using `pnpm gateway:watch`.
## Related docs
@@ -115,4 +115,4 @@ pnpm clawdis health
- `docs/configuration.md` (config schema + examples)
- `docs/discord.md` and `docs/telegram.md` (reply tags + replyToMode settings)
- `docs/clawd.md` (personal assistant setup)
- `docs/clawdis-mac.md` (macOS app behavior; gateway lifecycle + “Attach only”)
- `docs/clawdbot-mac.md` (macOS app behavior; gateway lifecycle + “Attach only”)
docs/signal.md
+15 -15
View File
@@ -9,19 +9,19 @@ read_when:
Status: external CLI integration only. No libsignal embedding.
## Why
- Signal OSS stack is GPL/AGPL; not compatible with Clawdis MIT if bundled.
- Signal OSS stack is GPL/AGPL; not compatible with Clawdbot MIT if bundled.
- signal-cli is unofficial; must stay up to date (Signal server churn).
## The “number model” (important)
- Clawdis is a **device** connected via `signal-cli`.
- If you run `signal-cli` on **your personal Signal account**, Clawdis will **not** respond to messages sent from that same account (loop protection: ignore sender==account).
- Clawdbot is a **device** connected via `signal-cli`.
- If you run `signal-cli` on **your personal Signal account**, Clawdbot will **not** respond to messages sent from that same account (loop protection: ignore sender==account).
- Result: you **cannot** “text yourself” to chat with the AI.
- For “I text her, she texts me back” you want a **separate Signal account/number for the bot**:
- Bot number runs `signal-cli` (linked device)
- Your personal number is in `signal.allowFrom`
- You DM the bot number; Clawdis replies back to you
- You DM the bot number; Clawdbot replies back to you
You can still run Clawdis on your own Signal account if your goal is “respond to other people as me”, but not for self-chat.
You can still run Clawdbot on your own Signal account if your goal is “respond to other people as me”, but not for self-chat.
## Model
- Run `signal-cli` as separate process (user-installed).
@@ -30,16 +30,16 @@ You can still run Clawdis on your own Signal account if your goal is “respond
## Quickstart (bot number)
1) Install `signal-cli` (keep Java installed).
- If you use the CLI wizard, it can auto-install to `~/.clawdis/tools/signal-cli/...`.
- If you use the CLI wizard, it can auto-install to `~/.clawdbot/tools/signal-cli/...`.
- If you want a pinned version (example: `v0.13.22`), install manually:
- Download the release asset for your platform from GitHub (tag `v0.13.22`).
- Extract it somewhere stable (example: `~/.clawdis/tools/signal-cli/0.13.22/`).
- Extract it somewhere stable (example: `~/.clawdbot/tools/signal-cli/0.13.22/`).
- Set `signal.cliPath` to the extracted `signal-cli` binary path.
2) Link the bot account as a device:
- Run: `signal-cli link -n "Clawdis"`
- Run: `signal-cli link -n "Clawdbot"`
- Scan QR in Signal: Settings → Linked Devices → Link New Device
- Verify: `signal-cli listAccounts` includes the bot E.164
3) Configure `~/.clawdis/clawdis.json`:
3) Configure `~/.clawdbot/clawdbot.json`:
```json5
{
signal: {
@@ -56,17 +56,17 @@ You can still run Clawdis on your own Signal account if your goal is “respond
}
```
4) Run gateway; sanity probe:
- `clawdis gateway call providers.status --params '{"probe":true}'`
- `clawdbot gateway call providers.status --params '{"probe":true}'`
- Expect `signal.probe.ok=true` and `signal.probe.version`.
5) DM the bot number from your phone; Clawdis replies.
5) DM the bot number from your phone; Clawdbot replies.
## “Do I need a separate number?”
- If you want “I text her and she texts me back”, yes: **use a separate Signal account/number for the bot**.
- Your personal account can run `signal-cli`, but you can’t self-chat (Signal loop protection; Clawdis ignores sender==account).
- Your personal account can run `signal-cli`, but you can’t self-chat (Signal loop protection; Clawdbot ignores sender==account).
If you have a second phone:
- Create/activate the bot number on that phone.
- Run `signal-cli link -n "Clawdis"` on your Mac, scan the QR on the bot phone.
- Run `signal-cli link -n "Clawdbot"` on your Mac, scan the QR on the bot phone.
- Put your personal number in `signal.allowFrom`, then DM the bot number from your personal phone.
## Endpoints (daemon --http)
@@ -94,12 +94,12 @@ If you have a second phone:
- Groups: `signal:group:<groupId>`
- Usernames: `username:<name>` / `u:<name>`
## Process plan (Clawdis adapter)
## Process plan (Clawdbot adapter)
1) Detect `signal-cli` binary; refuse if missing.
2) Launch daemon (HTTP preferred), store PID.
3) Poll `/api/v1/check` until ready.
4) Open SSE stream; parse `event: receive`.
5) Translate receive payload into Clawdis surface model.
5) Translate receive payload into Clawdbot surface model.
6) On SSE disconnect, backoff + reconnect.
## Storage
docs/skills-config.md
+2 -2
View File
@@ -6,7 +6,7 @@ read_when:
---
# Skills Config
All skills-related configuration lives under `skills` in `~/.clawdis/clawdis.json`.
All skills-related configuration lives under `skills` in `~/.clawdbot/clawdbot.json`.
```json5
{
@@ -54,5 +54,5 @@ Per-skill fields:
## Notes
- Keys under `entries` map to the skill name by default. If a skill defines
`metadata.clawdis.skillKey`, use that key instead.
`metadata.clawdbot.skillKey`, use that key instead.
- Changes to skills are picked up on the next new session.
docs/skills.md
+21 -21
View File
@@ -5,24 +5,24 @@ read_when:
- Changing skill gating or load rules
---
<!-- {% raw %} -->
# Skills (Clawdis)
# Skills (Clawdbot)
Clawdis uses **AgentSkills-compatible** skill folders to teach the agent how to use tools. Each skill is a directory containing a `SKILL.md` with YAML frontmatter and instructions. Clawdis loads **bundled skills** plus optional local overrides, and filters them at load time based on environment, config, and binary presence.
Clawdbot uses **AgentSkills-compatible** skill folders to teach the agent how to use tools. Each skill is a directory containing a `SKILL.md` with YAML frontmatter and instructions. Clawdbot loads **bundled skills** plus optional local overrides, and filters them at load time based on environment, config, and binary presence.
## Locations and precedence
Skills are loaded from **three** places:
1) **Bundled skills**: shipped with the install (npm package or Clawdis.app)
2) **Managed/local skills**: `~/.clawdis/skills`
1) **Bundled skills**: shipped with the install (npm package or Clawdbot.app)
2) **Managed/local skills**: `~/.clawdbot/skills`
3) **Workspace skills**: `<workspace>/skills`
If a skill name conflicts, precedence is:
`<workspace>/skills` (highest) → `~/.clawdis/skills` → bundled skills (lowest)
`<workspace>/skills` (highest) → `~/.clawdbot/skills` → bundled skills (lowest)
Additionally, you can configure extra skill folders (lowest precedence) via
`skills.load.extraDirs` in `~/.clawdis/clawdis.json`.
`skills.load.extraDirs` in `~/.clawdbot/clawdbot.json`.
## Format (AgentSkills + Pi-compatible)
@@ -41,21 +41,21 @@ Notes:
- `metadata` should be a **single-line JSON object**.
- Use `{baseDir}` in instructions to reference the skill folder path.
- Optional frontmatter keys:
- `homepage` — URL surfaced as “Website” in the macOS Skills UI (also supported via `metadata.clawdis.homepage`).
- `homepage` — URL surfaced as “Website” in the macOS Skills UI (also supported via `metadata.clawdbot.homepage`).
## Gating (load-time filters)
Clawdis **filters skills at load time** using `metadata` (single-line JSON):
Clawdbot **filters skills at load time** using `metadata` (single-line JSON):
```markdown
---
name: nano-banana-pro
description: Generate or edit images via Gemini 3 Pro Image
metadata: {"clawdis":{"requires":{"bins":["uv"],"env":["GEMINI_API_KEY"],"config":["browser.enabled"]},"primaryEnv":"GEMINI_API_KEY"}}
metadata: {"clawdbot":{"requires":{"bins":["uv"],"env":["GEMINI_API_KEY"],"config":["browser.enabled"]},"primaryEnv":"GEMINI_API_KEY"}}
---
```
Fields under `metadata.clawdis`:
Fields under `metadata.clawdbot`:
- `always: true` — always include the skill (skip other gates).
- `emoji` — optional emoji used by the macOS Skills UI.
- `homepage` — optional URL shown as “Website” in the macOS Skills UI.
@@ -63,7 +63,7 @@ Fields under `metadata.clawdis`:
- `requires.bins` — list; each must exist on `PATH`.
- `requires.anyBins` — list; at least one must exist on `PATH`.
- `requires.env` — list; env var must exist **or** be provided in config.
- `requires.config` — list of `clawdis.json` paths that must be truthy.
- `requires.config` — list of `clawdbot.json` paths that must be truthy.
- `primaryEnv` — env var name associated with `skills.entries.<name>.apiKey`.
- `install` — optional array of installer specs used by the macOS Skills UI (brew/node/go/uv).
@@ -73,19 +73,19 @@ Installer example:
---
name: gemini
description: Use Gemini CLI for coding assistance and Google search lookups.
metadata: {"clawdis":{"emoji":"♊️","requires":{"bins":["gemini"]},"install":[{"id":"brew","kind":"brew","formula":"gemini-cli","bins":["gemini"],"label":"Install Gemini CLI (brew)"}]}}
metadata: {"clawdbot":{"emoji":"♊️","requires":{"bins":["gemini"]},"install":[{"id":"brew","kind":"brew","formula":"gemini-cli","bins":["gemini"],"label":"Install Gemini CLI (brew)"}]}}
---
```
Notes:
- If multiple installers are listed, the gateway picks a **single** preferred option (brew when available, otherwise node).
- Node installs honor `skills.install.nodeManager` in `clawdis.json` (default: npm; options: npm/pnpm/yarn/bun).
- Node installs honor `skills.install.nodeManager` in `clawdbot.json` (default: npm; options: npm/pnpm/yarn/bun).
- Go installs: if `go` is missing and `brew` is available, the gateway installs Go via Homebrew first and sets `GOBIN` to Homebrew’s `bin` when possible.
If no `metadata.clawdis` is present, the skill is always eligible (unless
If no `metadata.clawdbot` is present, the skill is always eligible (unless
disabled in config or blocked by `skills.allowBundled` for bundled skills).
## Config overrides (`~/.clawdis/clawdis.json`)
## Config overrides (`~/.clawdbot/clawdbot.json`)
Bundled/managed skills can be toggled and supplied with env values:
@@ -110,18 +110,18 @@ Bundled/managed skills can be toggled and supplied with env values:
Note: if the skill name contains hyphens, quote the key (JSON5 allows quoted keys).
Config keys match the **skill name** by default. If a skill defines
`metadata.clawdis.skillKey`, use that key under `skills.entries`.
`metadata.clawdbot.skillKey`, use that key under `skills.entries`.
Rules:
- `enabled: false` disables the skill even if it’s bundled/installed.
- `env`: injected **only if** the variable isn’t already set in the process.
- `apiKey`: convenience for skills that declare `metadata.clawdis.primaryEnv`.
- `apiKey`: convenience for skills that declare `metadata.clawdbot.primaryEnv`.
- `allowBundled`: optional allowlist for **bundled** skills only. If set, only
bundled skills in the list are eligible (managed/workspace skills unaffected).
## Environment injection (per agent run)
When an agent run starts, Clawdis:
When an agent run starts, Clawdbot:
1) Reads skill metadata.
2) Applies any `skills.entries.<key>.env` or `skills.entries.<key>.apiKey` to
`process.env`.
@@ -132,12 +132,12 @@ This is **scoped to the agent run**, not a global shell environment.
## Session snapshot (performance)
Clawdis snapshots the eligible skills **when a session starts** and reuses that list for subsequent turns in the same session. Changes to skills or config take effect on the next new session.
Clawdbot snapshots the eligible skills **when a session starts** and reuses that list for subsequent turns in the same session. Changes to skills or config take effect on the next new session.
## Managed skills lifecycle
Clawdis ships a baseline set of skills as **bundled skills** as part of the
install (npm package or Clawdis.app). `~/.clawdis/skills` exists for local
Clawdbot ships a baseline set of skills as **bundled skills** as part of the
install (npm package or Clawdbot.app). `~/.clawdbot/skills` exists for local
overrides (for example, pinning/patching a skill without changing the bundled
copy). Workspace skills are user-owned and override both on name conflicts.
docs/surface.md
+1 -1
View File
@@ -12,7 +12,7 @@ Goal: make replies deterministic per channel while keeping one shared context fo
- **Surfaces** (channel labels): `whatsapp`, `webchat`, `telegram`, `discord`, `imessage`, `voice`, etc. Add `Surface` to inbound `MsgContext` so templates/agents can log which channel a turn came from. Routing is fixed: replies go back to the origin surface; the model doesn’t choose.
- **Reply context:** inbound replies include `ReplyToId`, `ReplyToBody`, and `ReplyToSender`, and the quoted context is appended to `Body` as a `[Replying to ...]` block.
- **Canonical direct session:** All direct chats collapse into the single `main` session by default (no config needed). Groups stay `surface:group:<id>` (rooms: `surface:channel:<id>`), so they remain isolated.
- **Session store:** Keys are resolved via `resolveSessionKey(scope, ctx, mainKey)`; the agent JSONL path lives under `~/.clawdis/sessions/<SessionId>.jsonl`.
- **Session store:** Keys are resolved via `resolveSessionKey(scope, ctx, mainKey)`; the agent JSONL path lives under `~/.clawdbot/sessions/<SessionId>.jsonl`.
- **WebChat:** Always attaches to `main`, loads the full session transcript so desktop reflects cross-surface history, and writes new turns back to the same session.
- **Implementation hints:**
- Set `Surface` in each ingress (WhatsApp gateway, WebChat bridge, Telegram, Discord, iMessage).
docs/tailscale.md
+7 -7
View File
@@ -6,7 +6,7 @@ read_when:
---
# Tailscale (Gateway dashboard)
Clawdis can auto-configure Tailscale **Serve** (tailnet) or **Funnel** (public) for the
Clawdbot can auto-configure Tailscale **Serve** (tailnet) or **Funnel** (public) for the
Gateway dashboard and WebSocket port. This keeps the Gateway bound to loopback while
Tailscale provides HTTPS, routing, and (for Serve) identity headers.
@@ -20,8 +20,8 @@ Tailscale provides HTTPS, routing, and (for Serve) identity headers.
Set `gateway.auth.mode` to control the handshake:
- `token` (default when `CLAWDIS_GATEWAY_TOKEN` is set)
- `password` (shared secret via `CLAWDIS_GATEWAY_PASSWORD` or config)
- `token` (default when `CLAWDBOT_GATEWAY_TOKEN` is set)
- `password` (shared secret via `CLAWDBOT_GATEWAY_PASSWORD` or config)
When `tailscale.mode = "serve"`, the gateway trusts Tailscale identity headers by
default unless you force `gateway.auth.mode` to `password` or set
@@ -54,18 +54,18 @@ Open: `https://<magicdns>/` (or your configured `gateway.controlUi.basePath`)
}
```
Prefer `CLAWDIS_GATEWAY_PASSWORD` over committing a password to disk.
Prefer `CLAWDBOT_GATEWAY_PASSWORD` over committing a password to disk.
## CLI examples
```bash
clawdis gateway --tailscale serve
clawdis gateway --tailscale funnel --auth password
clawdbot gateway --tailscale serve
clawdbot gateway --tailscale funnel --auth password
```
## Notes
- Tailscale Serve/Funnel requires the `tailscale` CLI to be installed and logged in.
- `tailscale.mode: "funnel"` refuses to start unless auth mode is `password` to avoid public exposure.
- Set `gateway.tailscale.resetOnExit` if you want Clawdis to undo `tailscale serve`
- Set `gateway.tailscale.resetOnExit` if you want Clawdbot to undo `tailscale serve`
or `tailscale funnel` configuration on shutdown.
docs/talk.md
+1 -1
View File
@@ -40,7 +40,7 @@ Supported keys:
- `seed`, `normalize`, `lang`, `output_format`, `latency_tier`
- `once`
## Config (clawdis.json)
## Config (clawdbot.json)
```json5
{
"talk": {
docs/telegram.md
+4 -4
View File
@@ -10,15 +10,15 @@ Updated: 2025-12-07
Status: ready for bot-mode use with grammY (long-polling by default; webhook supported when configured). Text + media send, mention-gated group replies with per-group overrides, and optional proxy support are implemented.
## Goals
- Let you talk to Clawdis via a Telegram bot in DMs and groups.
- Let you talk to Clawdbot via a Telegram bot in DMs and groups.
- Share the same `main` session used by WhatsApp/WebChat; groups stay isolated as `telegram:group:<chatId>`.
- Keep transport routing deterministic: replies always go back to the surface they arrived on.
## How it will work (Bot API)
1) Create a bot with @BotFather and grab the token.
2) Configure Clawdis with `TELEGRAM_BOT_TOKEN` (or `telegram.botToken` in `~/.clawdis/clawdis.json`).
2) Configure Clawdbot with `TELEGRAM_BOT_TOKEN` (or `telegram.botToken` in `~/.clawdbot/clawdbot.json`).
3) Run the gateway; it auto-starts Telegram only when a `telegram` config section exists **and** a bot token is set (unless `telegram.enabled = false`).
- If you prefer env vars, still add `telegram: { enabled: true }` to `~/.clawdis/clawdis.json` and set `TELEGRAM_BOT_TOKEN`.
- If you prefer env vars, still add `telegram: { enabled: true }` to `~/.clawdbot/clawdbot.json` and set `TELEGRAM_BOT_TOKEN`.
- **Long-polling** is the default.
- **Webhook mode** is enabled by setting `telegram.webhookUrl` (optionally `telegram.webhookSecret` / `telegram.webhookPath`).
- The webhook listener currently binds to `0.0.0.0:8787` and serves `POST /telegram-webhook` by default.
@@ -85,6 +85,6 @@ Behavior is controlled by `telegram.replyToMode`:
- ⏳ Add more grammY coverage (webhook payloads, media edge cases)
## Safety & ops
- Treat the bot token as a secret (equivalent to account control); prefer `TELEGRAM_BOT_TOKEN` or a locked-down config file (`chmod 600 ~/.clawdis/clawdis.json`).
- Treat the bot token as a secret (equivalent to account control); prefer `TELEGRAM_BOT_TOKEN` or a locked-down config file (`chmod 600 ~/.clawdbot/clawdbot.json`).
- Respect Telegram rate limits (429s); grammY throttling is enabled by default.
- Use a test bot for development to avoid hitting production chats.
docs/test.md
+1 -1
View File
@@ -32,4 +32,4 @@ Full cold-start flow in a clean Linux container:
scripts/e2e/onboard-docker.sh
```
This script drives the interactive wizard via a pseudo-tty, verifies config/workspace/session files, then starts the gateway and runs `clawdis health`.
This script drives the interactive wizard via a pseudo-tty, verifies config/workspace/session files, then starts the gateway and runs `clawdbot health`.
docs/tools.md
+10 -10
View File
@@ -1,14 +1,14 @@
---
summary: "Agent tool surface for Clawdis (browser, canvas, nodes, cron) replacing clawdis-* skills"
summary: "Agent tool surface for Clawdbot (browser, canvas, nodes, cron) replacing clawdbot-* skills"
read_when:
- Adding or modifying agent tools
- Retiring or changing clawdis-* skills
- Retiring or changing clawdbot-* skills
---
# Tools (Clawdis)
# Tools (Clawdbot)
Clawdis exposes **first-class agent tools** for browser, canvas, nodes, and cron.
These replace the old `clawdis-*` skills: the tools are typed, no shelling,
Clawdbot exposes **first-class agent tools** for browser, canvas, nodes, and cron.
These replace the old `clawdbot-*` skills: the tools are typed, no shelling,
and the agent should rely on them directly.
## Tool inventory
@@ -58,7 +58,7 @@ Common parameters:
- `controlUrl` (defaults from config)
- `profile` (optional; defaults to `browser.defaultProfile`)
Notes:
- Requires `browser.enabled=true` in `~/.clawdis/clawdis.json`.
- Requires `browser.enabled=true` in `~/.clawdbot/clawdbot.json`.
- Uses `browser.controlUrl` unless `controlUrl` is passed explicitly.
- All actions accept optional `profile` parameter for multi-instance support.
- When `profile` is omitted, uses `browser.defaultProfile` (defaults to "clawd").
@@ -83,7 +83,7 @@ Notes:
- Uses gateway `node.invoke` under the hood.
- If no `node` is provided, the tool picks a default (single connected node or local mac node).
- A2UI is v0.8 only (no `createSurface`); the CLI rejects v0.9 JSONL with line errors.
- Quick smoke: `clawdis canvas a2ui push --text "Hello from A2UI"`.
- Quick smoke: `clawdbot canvas a2ui push --text "Hello from A2UI"`.
### `nodes`
Discover and target paired nodes; send notifications; capture camera/screen.
@@ -117,7 +117,7 @@ Notes:
Restart the running Gateway process (in-place).
Core actions:
- `restart` (sends `SIGUSR1` to the current process; `clawdis gateway`/`gateway-daemon` restart in-place)
- `restart` (sends `SIGUSR1` to the current process; `clawdbot gateway`/`gateway-daemon` restart in-place)
Notes:
- Use `delayMs` (defaults to 2000) to avoid interrupting an in-flight reply.
@@ -230,6 +230,6 @@ In pi-mono:
- Agent loop: `packages/ai/src/agent/agent-loop.ts`
- Validates tool arguments and executes tools, then appends `toolResult` messages.
In Clawdis:
In Clawdbot:
- System prompt append: `src/agents/system-prompt.ts`
- Tool list injected via `createClawdisCodingTools()` in `src/agents/pi-tools.ts`
- Tool list injected via `createClawdbotCodingTools()` in `src/agents/pi-tools.ts`
docs/troubleshooting.md
+30 -30
View File
@@ -1,11 +1,11 @@
---
summary: "Quick troubleshooting guide for common Clawdis failures"
summary: "Quick troubleshooting guide for common Clawdbot failures"
read_when:
- Investigating runtime issues or failures
---
# Troubleshooting 🔧
When your CLAWDIS misbehaves, here's how to fix it.
When your CLAWDBOT misbehaves, here's how to fix it.
## Common Issues
@@ -24,18 +24,18 @@ The agent was interrupted mid-response.
**Check 1:** Is the sender in `whatsapp.allowFrom`?
```bash
cat ~/.clawdis/clawdis.json | jq '.whatsapp.allowFrom'
cat ~/.clawdbot/clawdbot.json | jq '.whatsapp.allowFrom'
```
**Check 2:** For group chats, is mention required?
```bash
# The message must match mentionPatterns or explicit mentions; defaults live in whatsapp.groups
cat ~/.clawdis/clawdis.json | jq '.routing.groupChat, .whatsapp.groups'
cat ~/.clawdbot/clawdbot.json | jq '.routing.groupChat, .whatsapp.groups'
```
**Check 3:** Check the logs
```bash
tail -f "$(ls -t /tmp/clawdis/clawdis-*.log | head -1)" | grep "blocked\\|skip\\|unauthorized"
tail -f "$(ls -t /tmp/clawdbot/clawdbot-*.log | head -1)" | grep "blocked\\|skip\\|unauthorized"
```
### Image + Mention Not Working
@@ -50,7 +50,7 @@ Known issue: When you send an image with ONLY a mention (no other text), WhatsAp
**Check 1:** Is the session file there?
```bash
ls -la ~/.clawdis/sessions/
ls -la ~/.clawdbot/sessions/
```
**Check 2:** Is `idleMinutes` too short?
@@ -82,26 +82,26 @@ Or use the `process` tool to background long commands.
```bash
# Check local status (creds, sessions, queued events)
clawdis status
clawdbot status
# Probe the running gateway + providers (WA connect + Telegram + Discord APIs)
clawdis status --deep
clawdbot status --deep
# View recent connection events
tail -100 /tmp/clawdis/clawdis-*.log | grep "connection\\|disconnect\\|logout"
tail -100 /tmp/clawdbot/clawdbot-*.log | grep "connection\\|disconnect\\|logout"
```
**Fix:** Usually reconnects automatically once the Gateway is running. If you’re stuck, restart the Gateway process (however you supervise it), or run it manually with verbose output:
```bash
clawdis gateway --verbose
clawdbot gateway --verbose
```
If you’re logged out / unlinked:
```bash
clawdis logout
rm -rf ~/.clawdis/credentials # if logout can't cleanly remove everything
clawdis login --verbose # re-scan QR
clawdbot logout
rm -rf ~/.clawdbot/credentials # if logout can't cleanly remove everything
clawdbot login --verbose # re-scan QR
```
### Media Send Failing
@@ -118,12 +118,12 @@ ls -la /path/to/your/image.jpg
**Check 3:** Check media logs
```bash
grep "media\\|fetch\\|download" "$(ls -t /tmp/clawdis/clawdis-*.log | head -1)" | tail -20
grep "media\\|fetch\\|download" "$(ls -t /tmp/clawdbot/clawdbot-*.log | head -1)" | tail -20
```
### High Memory Usage
CLAWDIS keeps conversation history in memory.
CLAWDBOT keeps conversation history in memory.
**Fix:** Restart periodically or set session limits:
```json
@@ -142,7 +142,7 @@ If the app disappears or shows "Abort trap 6" when you click "Allow" on a privac
**Fix 1: Reset TCC Cache**
```bash
tccutil reset All com.clawdis.mac.debug
tccutil reset All com.clawdbot.mac.debug
```
**Fix 2: Force New Bundle ID**
@@ -169,33 +169,33 @@ Get verbose logging:
```bash
# Turn on trace logging in config:
# ~/.clawdis/clawdis.json -> { logging: { level: "trace" } }
# ~/.clawdbot/clawdbot.json -> { logging: { level: "trace" } }
#
# Then run verbose commands to mirror debug output to stdout:
clawdis gateway --verbose
clawdis login --verbose
clawdbot gateway --verbose
clawdbot login --verbose
```
## Log Locations
| Log | Location |
|-----|----------|
| Main logs (default) | `/tmp/clawdis/clawdis-YYYY-MM-DD.log` |
| Session files | `~/.clawdis/sessions/` |
| Media cache | `~/.clawdis/media/` |
| Credentials | `~/.clawdis/credentials/` |
| Main logs (default) | `/tmp/clawdbot/clawdbot-YYYY-MM-DD.log` |
| Session files | `~/.clawdbot/sessions/` |
| Media cache | `~/.clawdbot/media/` |
| Credentials | `~/.clawdbot/credentials/` |
## Health Check
```bash
# Is the gateway reachable?
clawdis health --json
clawdbot health --json
# Is something listening on the default port?
lsof -nP -iTCP:18789 -sTCP:LISTEN
# Recent activity
tail -20 /tmp/clawdis/clawdis-*.log
tail -20 /tmp/clawdbot/clawdbot-*.log
```
## Reset Everything
@@ -203,19 +203,19 @@ tail -20 /tmp/clawdis/clawdis-*.log
Nuclear option:
```bash
rm -rf ~/.clawdis
clawdis login # re-pair WhatsApp
clawdis gateway # start the Gateway again
rm -rf ~/.clawdbot
clawdbot login # re-pair WhatsApp
clawdbot gateway # start the Gateway again
```
⚠️ This loses all sessions and requires re-pairing WhatsApp.
## Getting Help
1. Check logs first: `/tmp/clawdis/` (default: `clawdis-YYYY-MM-DD.log`, or your configured `logging.file`)
1. Check logs first: `/tmp/clawdbot/` (default: `clawdbot-YYYY-MM-DD.log`, or your configured `logging.file`)
2. Search existing issues on GitHub
3. Open a new issue with:
- CLAWDIS version
- CLAWDBOT version
- Relevant log snippets
- Steps to reproduce
- Your config (redact secrets!)
docs/tui.md
+3 -3
View File
@@ -1,5 +1,5 @@
---
summary: "Terminal UI (TUI) for Clawdis via the Gateway"
summary: "Terminal UI (TUI) for Clawdbot via the Gateway"
read_when:
- You want a terminal UI that connects to the Gateway from any machine
- You are debugging the TUI client or Gateway chat stream
@@ -15,12 +15,12 @@ Updated: 2026-01-03
## Run
```bash
clawdis tui
clawdbot tui
```
### Remote
```bash
clawdis tui --url ws://127.0.0.1:18789 --token <gateway-token>
clawdbot tui --url ws://127.0.0.1:18789 --token <gateway-token>
```
Use SSH tunneling or Tailscale to reach the Gateway WS.
docs/typebox.md
+1 -1
View File
@@ -12,7 +12,7 @@ We use TypeBox schemas in `src/gateway/protocol/schema.ts` as the single source
## Current pipeline
- **TypeBox → JSON Schema**: `pnpm protocol:gen` writes `dist/protocol.schema.json` (draft-07) and runs AJV in the server tests.
- **TypeBox → Swift**: `pnpm protocol:gen:swift` generates `apps/macos/Sources/ClawdisProtocol/GatewayModels.swift`.
- **TypeBox → Swift**: `pnpm protocol:gen:swift` generates `apps/macos/Sources/ClawdbotProtocol/GatewayModels.swift`.
## Problem
docs/voicewake.md
+2 -2
View File
@@ -6,7 +6,7 @@ read_when:
---
# Voice Wake (Global Wake Words)
Clawdis treats **wake words as a single global list** owned by the **Gateway**.
Clawdbot treats **wake words as a single global list** owned by the **Gateway**.
- There are **no per-node custom wake words**.
- **Any node/app UI may edit** the list; changes are persisted by the Gateway and broadcast to everyone.
@@ -16,7 +16,7 @@ Clawdis treats **wake words as a single global list** owned by the **Gateway**.
Wake words are stored on the gateway machine at:
- `~/.clawdis/settings/voicewake.json`
- `~/.clawdbot/settings/voicewake.json`
Shape:
docs/web.md
+8 -8
View File
@@ -9,7 +9,7 @@ read_when:
The Gateway serves a small **browser Control UI** (Vite + Lit) from the same port as the Gateway WebSocket:
- default: `http://<host>:18789/`
- optional prefix: set `gateway.controlUi.basePath` (e.g. `/clawdis`)
- optional prefix: set `gateway.controlUi.basePath` (e.g. `/clawdbot`)
The UI talks directly to the Gateway WS and supports:
- Chat (`chat.history`, `chat.send`, `chat.abort`)
@@ -20,7 +20,7 @@ The UI talks directly to the Gateway WS and supports:
- Cron (`cron.*`)
- Skills (`skills.status`, `skills.update`, `skills.install`)
- Nodes (`node.list`, `node.describe`, `node.invoke`)
- Config (`config.get`, `config.set`) for `~/.clawdis/clawdis.json`
- Config (`config.get`, `config.set`) for `~/.clawdbot/clawdbot.json`
- Debug (status/health/models snapshots + manual calls)
## Webhooks
@@ -36,7 +36,7 @@ You can control it via config:
```json5
{
gateway: {
controlUi: { enabled: true, basePath: "/clawdis" } // basePath optional
controlUi: { enabled: true, basePath: "/clawdbot" } // basePath optional
}
}
```
@@ -59,7 +59,7 @@ Keep the Gateway on loopback and let Tailscale Serve proxy it:
Then start the gateway:
```bash
clawdis gateway
clawdbot gateway
```
Open:
@@ -79,8 +79,8 @@ Open:
Then start the gateway (token required for non-loopback binds):
```bash
export CLAWDIS_GATEWAY_TOKEN="…your token…"
clawdis gateway
export CLAWDBOT_GATEWAY_TOKEN="…your token…"
clawdbot gateway
```
Open:
@@ -93,14 +93,14 @@ Open:
gateway: {
bind: "loopback",
tailscale: { mode: "funnel" },
auth: { mode: "password" } // or CLAWDIS_GATEWAY_PASSWORD
auth: { mode: "password" } // or CLAWDBOT_GATEWAY_PASSWORD
}
}
```
## Security notes
- Binding the Gateway to a non-loopback address **requires** auth (`CLAWDIS_GATEWAY_TOKEN` or `gateway.auth`).
- Binding the Gateway to a non-loopback address **requires** auth (`CLAWDBOT_GATEWAY_TOKEN` or `gateway.auth`).
- The UI sends `connect.params.auth.token` or `connect.params.auth.password`.
- Use `gateway.auth.allowTailscale: false` to require explicit credentials even in Serve mode.
- `gateway.tailscale.mode: "funnel"` requires `gateway.auth.mode: "password"` (shared password).
docs/webchat.md
+3 -3
View File
@@ -23,12 +23,12 @@ Updated: 2025-12-17
## Config
- WebChat does not have a separate HTTP port/config anymore.
- Gateway WS is configured via the app’s gateway endpoint settings (`GatewayEndpointStore`) or `clawdis gateway --port` when running locally.
- Gateway WS is configured via the app’s gateway endpoint settings (`GatewayEndpointStore`) or `clawdbot gateway --port` when running locally.
## Failure handling
- UI errors when the Gateway handshake fails or the WS drops.
- No fallback transport; the Gateway WS is required.
## Dev notes
- macOS glue: `apps/macos/Sources/Clawdis/WebChatSwiftUI.swift` + `apps/macos/Sources/Clawdis/WebChatManager.swift`.
- Remote tunnel helper: `apps/macos/Sources/Clawdis/RemotePortTunnel.swift`.
- macOS glue: `apps/macos/Sources/Clawdbot/WebChatSwiftUI.swift` + `apps/macos/Sources/Clawdbot/WebChatManager.swift`.
- Remote tunnel helper: `apps/macos/Sources/Clawdbot/RemotePortTunnel.swift`.
docs/webhook.md
+4 -4
View File
@@ -2,7 +2,7 @@
summary: "Webhook ingress for wake and isolated agent runs"
read_when:
- Adding or changing webhook endpoints
- Wiring external systems into Clawdis
- Wiring external systems into Clawdbot
---
# Webhooks
@@ -29,7 +29,7 @@ Notes:
Every request must include the hook token:
- `Authorization: Bearer <token>`
- or `x-clawdis-token: <token>`
- or `x-clawdbot-token: <token>`
- or `?token=<token>`
## Endpoints
@@ -92,7 +92,7 @@ Mapping options (summary):
- `hooks.transformsDir` + `transform.module` loads a JS/TS module for custom logic.
- Use `match.source` to keep a generic ingest endpoint (payload-driven routing).
- TS transforms require a TS loader (e.g. `tsx`) or precompiled `.js` at runtime.
- `clawdis hooks gmail setup` writes `hooks.gmail` config for `clawdis hooks gmail run`.
- `clawdbot hooks gmail setup` writes `hooks.gmail` config for `clawdbot hooks gmail run`.
## Responses
@@ -113,7 +113,7 @@ curl -X POST http://127.0.0.1:18789/hooks/wake \
```bash
curl -X POST http://127.0.0.1:18789/hooks/agent \
-H 'x-clawdis-token: SECRET' \
-H 'x-clawdbot-token: SECRET' \
-H 'Content-Type: application/json' \
-d '{"message":"Summarize inbox","name":"Email","wakeMode":"next-heartbeat"}'
```
docs/whatsapp.md
+5 -5
View File
@@ -34,10 +34,10 @@ WhatsApp requires a real mobile number for verification. VoIP and virtual number
**Tip:** The number only needs to receive one verification SMS. After that, WhatsApp Web sessions persist via `creds.json`.
## Login + credentials
- Login command: `clawdis login` (QR via Linked Devices).
- Credentials stored in `~/.clawdis/credentials/creds.json`.
- Login command: `clawdbot login` (QR via Linked Devices).
- Credentials stored in `~/.clawdbot/credentials/creds.json`.
- Backup copy at `creds.json.bak` (restored on corruption).
- Logout: `clawdis logout` deletes creds and session store.
- Logout: `clawdbot logout` deletes creds and session store.
- Logged-out socket => error instructs re-link.
## Inbound flow (DM + group)
@@ -93,7 +93,7 @@ WhatsApp requires a real mobile number for verification. VoIP and virtual number
- Caption only on first media item.
- Media fetch supports HTTP(S) and local paths.
- Animated GIFs: WhatsApp expects MP4 with `gifPlayback: true` for inline looping.
- CLI: `clawdis send --media <mp4> --gif-playback`
- CLI: `clawdbot send --media <mp4> --gif-playback`
- Gateway: `send` params include `gifPlayback: true`
## Media limits + optimization
@@ -133,7 +133,7 @@ WhatsApp requires a real mobile number for verification. VoIP and virtual number
## Logs + troubleshooting
- Subsystems: `whatsapp/inbound`, `whatsapp/outbound`, `web-heartbeat`, `web-reconnect`.
- Log file: `/tmp/clawdis/clawdis-YYYY-MM-DD.log` (configurable).
- Log file: `/tmp/clawdbot/clawdbot-YYYY-MM-DD.log` (configurable).
- Troubleshooting guide: `docs/refactor/web-gateway-troubleshooting.md`.
## Tests
docs/wizard.md
+10 -10
View File
@@ -7,20 +7,20 @@ read_when:
# Onboarding Wizard (CLI)
The onboarding wizard is the **recommended** way to set up Clawdis on any OS.
The onboarding wizard is the **recommended** way to set up Clawdbot on any OS.
It configures a local Gateway or a remote Gateway connection, plus providers, skills,
and workspace defaults in one guided flow.
Primary entrypoint:
```bash
clawdis onboard
clawdbot onboard
```
Follow‑up reconfiguration:
```bash
clawdis configure
clawdbot configure
```
## What the wizard does
@@ -40,7 +40,7 @@ It does **not** install or change anything on the remote host.
## Flow details (local)
1) **Existing config detection**
- If `~/.clawdis/clawdis.json` exists, choose **Keep / Modify / Reset**.
- If `~/.clawdbot/clawdbot.json` exists, choose **Keep / Modify / Reset**.
- Reset uses `trash` (never `rm`) and offers scopes:
- Config only
- Config + credentials + sessions
@@ -74,7 +74,7 @@ It does **not** install or change anything on the remote host.
- Windows: Scheduled Task
7) **Health check**
- Starts the Gateway (if needed) and runs `clawdis health`.
- Starts the Gateway (if needed) and runs `clawdbot health`.
8) **Skills (recommended)**
- Reads the available skills and checks requirements.
@@ -104,7 +104,7 @@ Notes:
Use `--non-interactive` to automate or script onboarding:
```bash
clawdis onboard --non-interactive \
clawdbot onboard --non-interactive \
--mode local \
--auth-choice apiKey \
--anthropic-api-key "$ANTHROPIC_API_KEY" \
@@ -124,7 +124,7 @@ Clients (macOS app, Control UI) can render steps without re‑implementing onboa
The wizard can install `signal-cli` from GitHub releases:
- Downloads the appropriate release asset.
- Stores it under `~/.clawdis/tools/signal-cli/<version>/`.
- Stores it under `~/.clawdbot/tools/signal-cli/<version>/`.
- Writes `signal.cliPath` to your config.
Notes:
@@ -134,7 +134,7 @@ Notes:
## What the wizard writes
Typical fields in `~/.clawdis/clawdis.json`:
Typical fields in `~/.clawdbot/clawdbot.json`:
- `agent.workspace`
- `agent.model` / `models.providers` (if Minimax chosen)
- `gateway.*` (mode, bind, auth, tailscale)
@@ -146,8 +146,8 @@ Typical fields in `~/.clawdis/clawdis.json`:
- `wizard.lastRunCommand`
- `wizard.lastRunMode`
WhatsApp credentials go to `~/.clawdis/credentials/`.
Sessions are stored under `~/.clawdis/sessions/`.
WhatsApp credentials go to `~/.clawdbot/credentials/`.
Sessions are stored under `~/.clawdbot/sessions/`.
## Related docs