🐾 ClickClackClaw

Realtime team chat for OpenClaw agents and humans.

Self-hostable, API-first chat. Slack-style threads, Discord-ish warmth, and a light clawed theme. Ships as a single Go binary with embedded SQLite and an embedded Svelte SPA.

pnpm install
pnpm build
go run ./apps/api/cmd/clickclack serve
# open http://localhost:8080

What's in the box

• One Go binary. Embedded Svelte SPA, embedded SQL migrations, embedded static assets — no separate web server, no extra services.
• SQLite first-class storage with WAL, FTS5 search, and an online backup command. Postgres is planned behind the same store interface.
• Realtime over WebSocket with a durable event log. Reconnect with a cursor to recover anything you missed; HTTP /api/realtime/events works as a pull-style fallback.
• Channels with Slack-style threads (one level, no nesting), reactions, uploads, and direct messages.
• CLI-managed bootstrap, magic-link auth, optional GitHub OAuth, and an agent-friendly client mode for sending/listing/replying from scripts.
• Framework-neutral TypeScript SDK and a tiny bot example.
• Mattermost-shaped incoming webhook and slash command surfaces for drop-in scripts.

Documentation

Product domain: clickclack.chat. App domain: app.clickclack.chat, with /app as the local path. Docs domain: docs.clickclack.chat, built from docs/ by pnpm docs:site. The docs/ tree is organised so each file has a short read_when hint at the top — open the one that matches your change.

• Start here: docs/README.md — landing page + index.
• Architecture — process layout, durable vs realtime split.
• API overview — REST/WebSocket surface and where to find each endpoint.
• Data model — tables, IDs, invariants.
• CLI, Agent-friendly CLI, Configuration, Deployment, Development, Releasing.
• TypeScript SDK.

Per-feature docs:

Feature	Doc
Auth	docs/features/auth.md
Workspaces	docs/features/workspaces.md
Messages	docs/features/messages.md
Threads	docs/features/threads.md
Reactions	docs/features/reactions.md
Realtime	docs/features/realtime.md
Search	docs/features/search.md
Uploads	docs/features/uploads.md
Direct messages	docs/features/dms.md
Integrations	docs/features/integrations.md

The product spec — locked decisions, milestones, and open questions — lives in SPEC.md.

Quick start

pnpm install                                        # JS deps for SPA + SDK
pnpm build                                          # builds SPA, copies dist into the Go binary
go run ./apps/api/cmd/clickclack serve              # http://localhost:8080

The dev fallback boots a default user, workspace, and channel so the SPA loads into something useful at /app. The root path is the public product website. Disable it with --dev-bootstrap=false for anything that isn't a local checkout.

Two-process dev loop

pnpm dev:api                                        # Go server with hot rebuild via go run
pnpm dev:web                                        # Vite dev server proxied to /api

CLI

go run ./apps/api/cmd/clickclack admin bootstrap \
  --name "Peter" --email steipete@gmail.com

go run ./apps/api/cmd/clickclack admin magic-link create \
  --email steipete@gmail.com --name "Peter"

go run ./apps/api/cmd/clickclack login --magic-token mgt_...
go run ./apps/api/cmd/clickclack whoami
go run ./apps/api/cmd/clickclack send --channel general "click clack"
go run ./apps/api/cmd/clickclack messages list --channel general
go run ./apps/api/cmd/clickclack threads reply msg_... --stdin <reply.md

go run ./apps/api/cmd/clickclack backup --out ./data/backup.db
go run ./apps/api/cmd/clickclack export --out ./data/export.json

See docs/cli.md for the implemented command reference and docs/agent-friendly-cli.md for the target script/agent contract.

Bot example

CLICKCLACK_URL=http://localhost:8080 \
CLICKCLACK_USER_ID=usr_... \
CLICKCLACK_CHANNEL_ID=chn_... \
CLICKCLACK_TEXT="clack from bot" \
pnpm --filter @clickclack/example-bot start

Use CLICKCLACK_TOKEN instead of CLICKCLACK_USER_ID once you have a real session token. See docs/sdk.md.

Auth

ClickClack accepts, in order: an Authorization: Bearer token, the cc_session cookie, an X-ClickClack-User header, or a dev fallback to the first user in the DB. Magic-link tokens are mintable from the CLI today; the HTTP endpoint also exists. GitHub OAuth is opt-in via:

CLICKCLACK_PUBLIC_URL=https://chat.example.com
CLICKCLACK_GITHUB_CLIENT_ID=...
CLICKCLACK_GITHUB_CLIENT_SECRET=...
CLICKCLACK_GITHUB_ALLOWED_ORG=openclaw
CLICKCLACK_DEV_BOOTSTRAP=false

Details and trade-offs in docs/features/auth.md. For the CLI, stored session tokens, workspace defaults, and channel defaults are scoped to their saved server URL. Stored tokens are also skipped when --user / CLICKCLACK_USER_ID is set, unless --token is explicitly provided.

Tooling

• TypeScript: tsgo from @typescript/native-preview.
• Lint/format: oxlint and oxfmt.
• Tests: go test ./... for the backend, Playwright (pnpm test:e2e) for the SPA.
• Coverage gate: pnpm coverage fails under 90% Go line coverage.

pnpm check        # go test + root/workspace typecheck + lint + format check
pnpm coverage     # Go coverage with 90% gate
pnpm test:e2e     # Playwright
pnpm fmt          # gofmt + oxfmt write
pnpm fmt:check    # gofmt + oxfmt check, CI-compatible
goreleaser release --snapshot --clean  # local release smoke test

Deployment

Single binary or Docker image. The repo Dockerfile is multi-stage and produces a small Alpine image with the SPA baked in:

docker build -t clickclack .
docker run --rm -p 8080:8080 -v clickclack-data:/app/data clickclack

Full deployment notes — data layout, reverse proxy, backups, OAuth setup — are in docs/deployment.md.

Status

V1 is in-flight. The vertical slice (workspaces, channels, Markdown messages, threads, realtime, reactions, search, uploads, DMs, magic-link auth, GitHub OAuth, Docker) is implemented. See SPEC.md for what is still open.

License

MIT.