feat: add Signal provider support
This commit is contained in:
Peter Steinberger
116
docs/setup.md
Normal file
116
docs/setup.md
Normal file
@@ -0,0 +1,116 @@
|
||||
---
|
||||
summary: "Setup guide: keep your Clawdis setup tailored while staying up-to-date"
|
||||
read_when:
|
||||
- Setting up a new machine
|
||||
- You want “latest + greatest” without breaking your personal setup
|
||||
---
|
||||
|
||||
# Setup
|
||||
|
||||
Last updated: 2026-01-01
|
||||
|
||||
## TL;DR
|
||||
- **Tailoring lives outside the repo:** `~/clawd` (workspace) + `~/.clawdis/clawdis.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**.
|
||||
|
||||
## Prereqs (from source)
|
||||
- Node `>=22`
|
||||
- `pnpm`
|
||||
|
||||
## Tailoring strategy (so updates don’t hurt)
|
||||
|
||||
If you want “100% tailored to me” *and* easy updates, keep your customization in:
|
||||
|
||||
- **Config:** `~/.clawdis/clawdis.json` (JSON/JSON5-ish)
|
||||
- **Workspace:** `~/clawd` (skills, prompts, memories; make it a private git repo)
|
||||
|
||||
Bootstrap once:
|
||||
|
||||
```bash
|
||||
clawdis setup
|
||||
```
|
||||
|
||||
From inside this repo, use the local CLI entry:
|
||||
|
||||
```bash
|
||||
pnpm clawdis setup
|
||||
```
|
||||
|
||||
## Stable workflow (macOS app first)
|
||||
|
||||
1) Install + launch **Clawdis.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
|
||||
```
|
||||
|
||||
5) Sanity check:
|
||||
|
||||
```bash
|
||||
clawdis health
|
||||
```
|
||||
|
||||
If onboarding is still WIP/broken on your build:
|
||||
- Run `clawdis setup`, then `clawdis login`, then start the Gateway manually (`clawdis gateway`).
|
||||
|
||||
## Bleeding edge workflow (Gateway in a terminal)
|
||||
|
||||
Goal: work on the TypeScript Gateway, get hot reload, keep the macOS app UI attached.
|
||||
|
||||
### 0) (Optional) Run the macOS app from source too
|
||||
|
||||
If you also want the macOS app on the bleeding edge:
|
||||
|
||||
```bash
|
||||
./scripts/restart-mac.sh
|
||||
```
|
||||
|
||||
### 1) Start the dev Gateway
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
pnpm gateway:watch
|
||||
```
|
||||
|
||||
`gateway:watch` runs `src/index.ts gateway --force` and reloads on `src/**/*.ts` changes.
|
||||
|
||||
### 2) Point the macOS app at your running Gateway
|
||||
|
||||
In **Clawdis.app**:
|
||||
|
||||
- Connection Mode: **Local**
|
||||
- Settings → **Debug Settings** → **Gateway** → enable **Attach only**
|
||||
|
||||
This makes the app **only connect to an already-running gateway** and **never spawn** its own.
|
||||
|
||||
### 3) Verify
|
||||
|
||||
- In-app Gateway status should read **“Using existing gateway …”**
|
||||
- Or via CLI:
|
||||
|
||||
```bash
|
||||
pnpm clawdis 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/`
|
||||
|
||||
## Updating (without wrecking your setup)
|
||||
|
||||
- Keep `~/clawd` and `~/.clawdis/` as “your stuff”; don’t put personal prompts/config into the `clawdis` repo.
|
||||
- Updating source: `git pull` + `pnpm install` (when lockfile changed) + keep using `pnpm gateway:watch`.
|
||||
|
||||
## Related docs
|
||||
|
||||
- `docs/gateway.md` (Gateway runbook; flags, supervision, ports)
|
||||
- `docs/configuration.md` (config schema + examples)
|
||||
- `docs/clawd.md` (personal assistant setup)
|
||||
- `docs/clawdis-mac.md` (macOS app behavior; gateway lifecycle + “Attach only”)
|
||||
46
docs/signal.md
Normal file
46
docs/signal.md
Normal file
@@ -0,0 +1,46 @@
|
||||
# Signal (signal-cli)
|
||||
|
||||
Status: external CLI integration only. No libsignal embedding.
|
||||
|
||||
## Why
|
||||
- Signal OSS stack is GPL/AGPL; not compatible with Clawdis MIT if bundled.
|
||||
- signal-cli is unofficial; must stay up to date (Signal server churn).
|
||||
|
||||
## Model
|
||||
- Run `signal-cli` as separate process (user-installed).
|
||||
- Prefer `daemon --http=127.0.0.1:PORT` for JSON-RPC + SSE.
|
||||
- Alternative: `jsonRpc` mode over stdin/stdout.
|
||||
|
||||
## Endpoints (daemon --http)
|
||||
- `POST /api/v1/rpc` JSON-RPC request (single or batch).
|
||||
- `GET /api/v1/events` SSE stream of `receive` notifications.
|
||||
- `GET /api/v1/check` health probe (200 = up).
|
||||
|
||||
## Multi-account
|
||||
- Start daemon without `-a`.
|
||||
- Include `params.account` (E164) on JSON-RPC calls.
|
||||
- SSE `?account=+E164` filters events; no param = all accounts.
|
||||
|
||||
## Minimal RPC surface
|
||||
- `send` (recipient/groupId/username, message, attachments).
|
||||
- `listGroups` (map group IDs).
|
||||
- `subscribeReceive` / `unsubscribeReceive` (if manual receive).
|
||||
- `startLink` / `finishLink` (optional device link flow).
|
||||
|
||||
## Process plan (Clawdis 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.
|
||||
6) On SSE disconnect, backoff + reconnect.
|
||||
|
||||
## Storage
|
||||
- signal-cli data lives in `$XDG_DATA_HOME/signal-cli/data` or
|
||||
`$HOME/.local/share/signal-cli/data`.
|
||||
|
||||
## References (local)
|
||||
- `~/Projects/oss/signal-cli/README.md`
|
||||
- `~/Projects/oss/signal-cli/man/signal-cli-jsonrpc.5.adoc`
|
||||
- `~/Projects/oss/signal-cli/src/main/java/org/asamk/signal/http/HttpServerHandler.java`
|
||||
- `~/Projects/oss/signal-cli/src/main/java/org/asamk/signal/jsonrpc/SignalJsonRpcDispatcherHandler.java`
|
||||
Reference in New Issue
Block a user