clickclack

💬 ClickClack

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 available behind the same store interface for hosted deployments that need external durable storage.
• 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, direct messages, and a guest waiting-room path with moderator approvals, timeouts, and blocks.
• 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:

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 --dev-bootstrap=true

For a fresh local checkout, --dev-bootstrap=true boots a default user, workspace, and channel so the SPA loads into something useful at /app. The root path is the public product website. Production and Docker defaults leave dev auth disabled.

Two-process dev loop

pnpm dev:api                                        # Go server with dev bootstrap enabled
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_TOKEN=ccb_... \
CLICKCLACK_CHANNEL_ID=chn_... \
CLICKCLACK_TEXT="clack from bot" \
pnpm --filter @clickclack/example-bot start

Create bot tokens with clickclack admin bot create. See docs/features/bots.md, docs/bot-installs.md, and docs/sdk.md.

Auth

ClickClack accepts, in order: an Authorization: Bearer session or bot 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=...
# Optional org gate:
# CLICKCLACK_GITHUB_ALLOWED_ORG=openclaw
# Optional moderator org for open guest login:
# CLICKCLACK_GITHUB_MODERATOR_ORG=openclaw

Without the org gate, GitHub users land in an isolated Guests workspace. When CLICKCLACK_GITHUB_MODERATOR_ORG is set, matching org members become moderators and non-members start as waiting-room guests with a three-post daily budget until a moderator approves them; if it is unset, open-login users join as normal members. See docs/features/moderation.md.

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 85% Go line coverage.

pnpm check        # go test + root/workspace typecheck + lint + format check
pnpm coverage     # Go coverage with 85% 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, guest-room moderation, Postgres, R2 uploads, Docker) is implemented. See SPEC.md for what is still open.

License

MIT.