chore: rename project to clawdbot
This commit is contained in:
Peter Steinberger
@@ -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` |
|
||||
|
||||
Reference in New Issue
Block a user