diff --git a/README.md b/README.md index e82f546b4..165056ef5 100644 --- a/README.md +++ b/README.md @@ -20,10 +20,11 @@ It answers you on the providers you already use (WhatsApp, Telegram, Slack, Disc If you want a personal, single-user assistant that feels local, fast, and always-on, this is it. -[Website](https://clawdbot.com) · [Docs](https://docs.clawd.bot) · Updating: [https://docs.clawd.bot/updating](https://docs.clawd.bot/updating) · Showcase: [https://docs.clawd.bot/showcase](https://docs.clawd.bot/showcase) · FAQ: [https://docs.clawd.bot/faq](https://docs.clawd.bot/faq) · Wizard: [https://docs.clawd.bot/wizard](https://docs.clawd.bot/wizard) · Nix: [https://github.com/clawdbot/nix-clawdbot](https://github.com/clawdbot/nix-clawdbot) · Docker: [https://docs.clawd.bot/docker](https://docs.clawd.bot/docker) · Discord: [https://discord.gg/clawd](https://discord.gg/clawd) +[Website](https://clawdbot.com) · [Docs](https://docs.clawd.bot) · Getting Started: [https://docs.clawd.bot/getting-started](https://docs.clawd.bot/getting-started) · Updating: [https://docs.clawd.bot/updating](https://docs.clawd.bot/updating) · Showcase: [https://docs.clawd.bot/showcase](https://docs.clawd.bot/showcase) · FAQ: [https://docs.clawd.bot/faq](https://docs.clawd.bot/faq) · Wizard: [https://docs.clawd.bot/wizard](https://docs.clawd.bot/wizard) · Nix: [https://github.com/clawdbot/nix-clawdbot](https://github.com/clawdbot/nix-clawdbot) · Docker: [https://docs.clawd.bot/docker](https://docs.clawd.bot/docker) · Discord: [https://discord.gg/clawd](https://discord.gg/clawd) Preferred setup: run the onboarding wizard (`clawdbot onboard`). It walks through gateway, workspace, providers, and skills. The CLI wizard is the recommended path and works on **macOS, Windows, and Linux**. Works with npm, pnpm, or bun. +New install? Start here: https://docs.clawd.bot/getting-started **Subscriptions (OAuth):** - **Anthropic** (Claude Pro/Max) @@ -35,6 +36,8 @@ Model note: while any model is supported, I strongly recommend **Anthropic Pro/M Do **not** download prebuilt binaries. Run from source. +Prefer **Bun**. `pnpm` is also supported (see https://docs.clawd.bot/getting-started). + ```bash # Clone this repo git clone https://github.com/clawdbot/clawdbot.git @@ -43,35 +46,21 @@ cd clawdbot bun install bun run ui:install bun run ui:build +bun run build bun run clawdbot onboard ``` -Note: `bun run build` is optional here (it produces `dist/` for running via Node / the packaged `clawdbot` binary). `bun run clawdbot ...` runs TypeScript directly. +Note: `bun run clawdbot ...` runs TypeScript directly. `bun run build` produces `dist/` for running via Node / the packaged `clawdbot` binary. -## Quick start (from source) +## Quick start (TL;DR) Runtime: **Node ≥22**. -From source, **pnpm** is the default workflow. Bun is supported as an optional local workflow; see [Bun](https://docs.clawd.bot/bun). +Full beginner guide (auth, pairing, providers): https://docs.clawd.bot/getting-started ```bash -# Install deps (no Bun lockfile) -bun install --no-save - -# Build TypeScript -bun run build - -# Build Control UI -bun install --cwd ui --no-save -bun run --cwd ui build - -# Recommended: run the onboarding wizard bun run clawdbot onboard -# Link WhatsApp (stores creds in ~/.clawdbot/credentials) -bun run clawdbot login - -# Start the gateway bun run clawdbot gateway --port 18789 --verbose # Dev loop (auto-reload on TS changes) diff --git a/docs/bun.md b/docs/bun.md index a3350357a..a009ea848 100644 --- a/docs/bun.md +++ b/docs/bun.md @@ -1,22 +1,34 @@ -# Bun (optional) +--- +summary: "Bun workflow (preferred): installs, patches, and gotchas vs pnpm" +read_when: + - You want the fastest local dev loop (bun + watch) + - You hit Bun install/patch/lifecycle script issues +--- -Goal: allow running this repo with Bun without maintaining a Bun lockfile or losing pnpm patch behavior. +# Bun + +Goal: run this repo with **Bun** (preferred) without losing pnpm patch behavior. ## Status -- pnpm remains the primary package manager/runtime for this repo. -- Bun can be used for local installs/builds/tests, but Bun currently **cannot use** `pnpm-lock.yaml` and will ignore it. +- Bun is the preferred local runtime for running TypeScript directly (`bun run …`, `bun --watch …`). +- `pnpm` is still fully supported (and used by some docs tooling). +- Bun cannot use `pnpm-lock.yaml` and will ignore it. -## Install (no Bun lockfile) +## Install -Use Bun without writing `bun.lock`/`bun.lockb`: +Default: + +```sh +bun install +``` + +Note: `bun.lock`/`bun.lockb` are gitignored, so there’s no repo churn either way. If you want *no lockfile writes*: ```sh bun install --no-save ``` -This avoids maintaining two lockfiles. (`bun.lock`/`bun.lockb` are gitignored.) - ## Build / Test (Bun) ```sh diff --git a/docs/docs.json b/docs/docs.json index 26ceef64b..8802512e9 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -23,23 +23,25 @@ "navigation": { "groups": [ { - "group": "Getting Started", + "group": "Start Here", "pages": [ + "getting-started", + "wizard", "index", + "setup", + "pairing", + "faq", + "clawd", "showcase", "hubs", - "onboarding", - "clawd", - "faq" + "onboarding" ] }, { - "group": "Installation", + "group": "Install Options", "pages": [ - "wizard", "nix", - "docker", - "setup" + "docker" ] }, { diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 000000000..5ebe6dc44 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,133 @@ +--- +summary: "Beginner guide: from repo checkout to first message (wizard, auth, providers, pairing)" +read_when: + - First time setup from zero + - You want the fastest path from checkout → onboarding → first message +--- + +# Getting Started + +Goal: go from **zero** → **first working chat** (with sane defaults) as quickly as possible. + +Recommended path: use the **CLI onboarding wizard** (`clawdbot onboard`). It sets up: +- model/auth (OAuth recommended) +- gateway settings +- providers (WhatsApp/Telegram/Discord/…) +- pairing defaults (secure DMs) +- workspace bootstrap + skills +- optional background daemon + +If you want the deeper reference pages, jump to: [Wizard](https://docs.clawd.bot/wizard), [Setup](https://docs.clawd.bot/setup), [Pairing](https://docs.clawd.bot/pairing), [Security](https://docs.clawd.bot/security). + +## 0) Prereqs + +- Node `>=22` +- `bun` (preferred) or `pnpm` +- Git + +macOS: if you plan to build the apps, install Xcode / CLT. For the CLI + gateway only, Node is enough. + +## 1) Check out from source + +```bash +git clone https://github.com/clawdbot/clawdbot.git +cd clawdbot +bun install +``` + +Note: `pnpm` is also supported: + +```bash +pnpm install +``` + +## 2) Build the Control UI (recommended) + +The Gateway serves the browser dashboard (Control UI) when assets exist. + +```bash +bun run ui:install +bun run ui:build +bun run build +``` + +If you skip UI build, the gateway still works — you just won’t get the dashboard. + +## 3) Run the onboarding wizard + +```bash +bun run clawdbot onboard +``` + +What you’ll choose: +- **Local vs Remote** gateway +- **Auth**: Anthropic OAuth or OpenAI OAuth (recommended), API key (optional), or skip for now +- **Providers**: WhatsApp QR login, bot tokens, etc. +- **Daemon**: optional background install (launchd/systemd/Task Scheduler) + +Wizard doc: https://docs.clawd.bot/wizard + +### Auth: where it lives (important) + +- OAuth credentials: `~/.clawdbot/credentials/oauth.json` +- Auth profiles (OAuth + API keys): `~/.clawdbot/agent/auth-profiles.json` + +Headless/server tip: do OAuth on a normal machine first, then copy `oauth.json` to the gateway host. + +## 4) Start the Gateway + +If the wizard didn’t start it for you: + +```bash +bun run clawdbot gateway --port 18789 --verbose +``` + +Dashboard (local loopback): `http://127.0.0.1:18789/` + +## 5) Pair + connect your first chat surface + +### WhatsApp (QR login) + +```bash +bun run clawdbot login +``` + +Scan via WhatsApp → Settings → Linked Devices. + +WhatsApp doc: https://docs.clawd.bot/whatsapp + +### Telegram / Discord / others + +The wizard can write tokens/config for you. If you prefer manual config, start with: +- Telegram: https://docs.clawd.bot/telegram +- Discord: https://docs.clawd.bot/discord + +## 6) DM safety (pairing approvals) + +Default posture: unknown DMs get a short code and messages are not processed until approved. + +Approve: + +```bash +bun run clawdbot pairing list --provider telegram +bun run clawdbot pairing approve --provider telegram +``` + +Pairing doc: https://docs.clawd.bot/pairing + +## 7) Verify end-to-end + +In a new terminal: + +```bash +bun run clawdbot health +bun run clawdbot send --to +15555550123 --message "Hello from Clawdbot" +``` + +If `health` shows “no auth configured”, go back to the wizard and set OAuth/key auth — the agent won’t be able to respond without it. + +## Next steps (optional, but great) + +- macOS menu bar app + voice wake: https://docs.clawd.bot/macos +- iOS/Android nodes (Canvas/camera/voice): https://docs.clawd.bot/nodes +- Remote access (SSH tunnel / Tailscale Serve): https://docs.clawd.bot/remote and https://docs.clawd.bot/tailscale diff --git a/docs/hubs.md b/docs/hubs.md index 6b3d99907..2dad7836a 100644 --- a/docs/hubs.md +++ b/docs/hubs.md @@ -10,6 +10,7 @@ Use these hubs to discover every page, including deep dives and reference docs t ## Start here - [Index](https://docs.clawd.bot) +- [Getting Started](https://docs.clawd.bot/getting-started) - [Onboarding](https://docs.clawd.bot/onboarding) - [Wizard](https://docs.clawd.bot/wizard) - [Setup](https://docs.clawd.bot/setup) diff --git a/docs/index.md b/docs/index.md index 6b7f82470..3243c7bea 100644 --- a/docs/index.md +++ b/docs/index.md @@ -26,16 +26,22 @@ read_when: 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. +## Start here + +- **New install from zero:** https://docs.clawd.bot/getting-started +- **Guided setup (recommended):** https://docs.clawd.bot/wizard (`clawdbot onboard`) + ## How it works ``` WhatsApp / Telegram / Discord │ ▼ - ┌──────────────────────────┐ + ┌───────────────────────────┐ │ Gateway │ ws://127.0.0.1:18789 (loopback-only) │ (single source) │ tcp://0.0.0.0:18790 (Bridge) - │ │ http://:18793/__clawdbot__/canvas/ (Canvas host) + │ │ http://:18793 + │ │ /__clawdbot__/canvas/ (Canvas host) └───────────┬───────────────┘ │ ├─ Pi agent (RPC)