clawdbot 2026.1.4

package/docs/clawd.md

@@ -0,0 +1,199 @@
+---
+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 CLAWDBOT (Clawd-style)
+
+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
+
+You’re putting an agent in a position to:
+- run commands on your machine (depending on your Pi tool setup)
+- read/write files in your workspace
+- send messages back out via WhatsApp/Telegram/Discord
+
+Start conservative:
+- Always set `whatsapp.allowFrom` (never run open-to-the-world on your personal Mac).
+- Use a dedicated WhatsApp number for the assistant.
+- Keep heartbeats disabled until you trust the setup (omit `agent.heartbeat` or set `agent.heartbeat.every: "0m"`).
+
+## Prerequisites
+
+- Node **22+**
+- 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):
+
+```bash
+pnpm install
+pnpm build
+pnpm link --global
+```
+
+## The two-phone setup (recommended)
+
+You want this:
+
+```
+Your Phone (personal)          Second Phone (assistant)
+┌─────────────────┐           ┌─────────────────┐
+│  Your WhatsApp  │  ──────▶  │  Assistant WA   │
+│  +1-555-YOU     │  message  │  +1-555-CLAWD   │
+└─────────────────┘           └────────┬────────┘
+                                       │ linked via QR
+                                       ▼
+                              ┌─────────────────┐
+                              │  Your Mac       │
+                              │  (clawdbot)      │
+                              │    Pi agent     │
+                              └─────────────────┘
+```
+
+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
+clawdbot login
+```
+
+2) Start the Gateway (leave it running):
+
+```bash
+clawdbot gateway --port 18789
+```
+
+3) Put a minimal config in `~/.clawdbot/clawdbot.json`:
+
+```json5
+{
+  whatsapp: {
+    allowFrom: ["+15555550123"]
+  }
+}
+```
+
+Now message the assistant number from your allowlisted phone.
+
+## Give the agent a workspace (AGENTS.md)
+
+Clawd reads operating instructions and “memory” from its workspace directory.
+
+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
+clawdbot setup
+```
+
+Optional: choose a different workspace with `agent.workspace` (supports `~`).
+
+```json5
+{
+  agent: {
+    workspace: "~/clawd"
+  }
+}
+```
+
+## The config that turns it into “an assistant”
+
+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)
+
+Example:
+
+```json5
+{
+  logging: { level: "info" },
+  agent: {
+    model: "anthropic/claude-opus-4-5",
+    workspace: "~/clawd",
+    thinkingDefault: "high",
+    timeoutSeconds: 1800,
+    // Start with 0; enable later.
+    heartbeat: { every: "0m" }
+  },
+  whatsapp: {
+    allowFrom: ["+15555550123"],
+    groups: {
+      "*": { requireMention: true }
+    }
+  },
+  routing: {
+    groupChat: {
+      mentionPatterns: ["@clawd", "clawd"]
+    }
+  },
+  session: {
+    scope: "per-sender",
+    resetTriggers: ["/new", "/reset"],
+    idleMinutes: 10080
+  }
+}
+```
+
+## Sessions and memory
+
+- 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, CLAWDBOT periodically runs a heartbeat prompt (default: `HEARTBEAT`).
+
+- If the agent replies with `HEARTBEAT_OK` (exact token), CLAWDBOT suppresses outbound delivery for that heartbeat.
+
+```json5
+{
+  agent: {
+    heartbeat: { every: "30m" }
+  }
+}
+```
+
+## Media in and out
+
+Inbound attachments (images/audio/docs) can be surfaced to your command via templates:
+- `{{MediaPath}}` (local temp file path)
+- `{{MediaUrl}}` (pseudo-URL)
+- `{{Transcript}}` (if audio transcription is enabled)
+
+Outbound attachments from the agent: include `MEDIA:<path-or-url>` on its own line (no spaces). Example:
+
+```
+Here’s the screenshot.
+MEDIA:/tmp/screenshot.png
+```
+
+CLAWDBOT extracts these and sends them as media alongside the text.
+
+## Operations checklist
+
+```bash
+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/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: [Clawdbot macOS app](./clawdbot-mac.md)
+- Security: [Security](./security.md)
+<!-- {% endraw %} -->

package/docs/clawdbot-mac.md

@@ -0,0 +1,104 @@
+---
+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
+---
+# Clawdbot macOS Companion (menu bar + gateway broker)
+
+Author: steipete · Status: draft spec · Date: 2025-12-20
+
+## Purpose
+- 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 (`clawdbot`) by symlinking the bundled binary.
+
+## High-level design
+- SwiftPM package in `apps/macos/` (macOS 15+, Swift 6).
+- Targets:
+  - `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/`:
+  - `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 `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 `~/.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.
+
+### Node commands (mac)
+- Canvas: `canvas.present|navigate|eval|snapshot|a2ui.*`
+- Camera: `camera.snap|camera.clip`
+- Screen: `screen.record`
+- System: `system.run` (shell) and `system.notify`
+
+### Permission advertising
+- 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 (`clawdbot`)
+- The **only** CLI is `clawdbot` (TS/bun). There is no `clawdbot-mac` helper.
+- For mac‑specific actions, the CLI uses `node.invoke`:
+  - `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.
+- Remote mode skips local gateway/CLI steps.
+- Selecting Local auto-enables the bundled Gateway via launchd (unless “Attach only” debug mode is enabled).
+
+## Deep links (URL scheme)
+
+Clawdbot (the macOS app) registers a URL scheme for triggering local actions from anywhere (browser, Shortcuts, CLI, etc.).
+
+Scheme:
+- `clawdbot://…`
+
+### `clawdbot://agent`
+
+Triggers a Gateway `agent` request (same machinery as WebChat/agent runs).
+
+Example:
+
+```bash
+open 'clawdbot://agent?message=Hello%20from%20deep%20link'
+```
+
+Query parameters:
+- `message` (required): the agent prompt (URL-encoded).
+- `sessionKey` (optional): explicit session key to use.
+- `thinking` (optional): thinking hint (e.g. `low`; omit for default).
+- `deliver` (optional): `true|false` (default: false).
+- `to` / `channel` (optional): forwarded to the Gateway `agent` method (only meaningful with `deliver=true`).
+- `timeoutSeconds` (optional): timeout hint forwarded to the Gateway.
+- `key` (optional): unattended mode key (see below).
+
+Safety/guardrails:
+- Always enabled.
+- Without a `key` query param, the app will prompt for confirmation before invoking the agent.
+- 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, 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 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`.
+
+## Open questions / decisions
+- Should `system.run` support streaming stdout/stderr or keep buffered responses only?
+- Should we allow node‑side permission prompts, or always require explicit app UI action?