GitHub - Artificer-Innovations/nanoclaw-webchat: Web chat interface for NanoClaw AI agent framework

Talk to your NanoClaw agents from a local browser tab — lobby @mentions, per-agent DMs, threading, attachments, and an optional MCP server for Cursor.

→ Get started — QUICKSTART.md

Prerequisites: Node.js 22 LTS, pnpm, and a working NanoClaw fork. See QUICKSTART.md.

pnpm add nanoclaw-webchat ws
pnpm exec nanoclaw-webchat install
# rebuild and restart your NanoClaw host, then open http://127.0.0.1:3200

Why this exists

NanoClaw runs multiple AI agents with real tooling and persistent workspaces. You need a local-first chat desk to reach them — not Slack, not a hosted SaaS widget, and not another standalone agent runtime.

nanoclaw-webchat is an opinionated channel add-on for an existing NanoClaw fork:

Localhost-only — default binds to 127.0.0.1, secret injected by the host
Optional public auth — cookie sessions, login page, GitHub/OIDC, shared-password login for network deployments (setup guide)
Multi-agent lobby — @sarah-style routing with engaged agents that keep listening after a mention
Per-agent DMs — direct 1:1 rooms when you don't want a shared lobby
Threading — multiple conversation threads per room, persisted in SQLite
Same delivery path — messages flow through NanoClaw's normal router, not a side channel

This package ships the browser UI, channel adapter templates, install skill, CLI, and MCP server. You still need a working NanoClaw fork — this is not NanoClaw itself.

Screenshots

Lobby with `@mentions` and engaged agents	Sidebar: rooms, DMs, threads

Direct message	Attachment preview drawer

Features

Area	Details
Lobby	Shared room; route to agents with `@folder` mentions; engaged-agent chips stay active until dismissed
DMs	One room per agent (`dm:<folder>`)
Threads	Create, rename, delete threads per room; unread badges in the sidebar
Messages	Markdown (GFM), code blocks, `@mention` highlighting
Attachments	Drag-and-drop files; resizable preview drawer (images, PDF, code, CSV, markdown)
Theme	Light / dark / system
Persistence	History in host `data/webchat.db`
CLI	`install`, `upgrade`, `sync-skill`, `verify`, `uninstall`
Auth	Local token (default) or public mode: basic login, OIDC/OAuth (e.g. GitHub), per-user rooms
MCP	Bundled `nanoclaw-webchat-mcp` bin — list channels, read/send messages from Cursor
Skill	`/add-webchat` Claude Code install flow

Quick install

Requires Node.js ≥ 20, pnpm, and a running NanoClaw fork.

cd /path/to/your-nanoclaw-fork
pnpm add nanoclaw-webchat ws
pnpm exec nanoclaw-webchat sync-skill
/add-webchat    # in Claude Code, or: pnpm exec nanoclaw-webchat install
pnpm run build && restart host
open http://127.0.0.1:3200

Full walkthrough: QUICKSTART.md

Configuration

Local mode (default)

Variable	Required	Default	Description
`WEBCHAT_ENABLED`	yes	—	Set `true` to start the channel
`WEBCHAT_PORT`	no	`3200`	HTTP/WebSocket port
`WEBCHAT_SECRET`	yes	—	Bearer token (injected into served HTML in local mode)
`WEBCHAT_USER_ID`	no	`web:local`	User id for outbound messages
`WEBCHAT_DISPLAY_NAME`	no	`Local`	Display name in the UI
`WEBCHAT_TEAM_FOLDER`	no	—	Agent folder for `@team` mentions

Public auth mode

Set WEBCHAT_AUTH_MODE=public for login-protected deployments (VPN, tailnet, or internet with HTTPS). Requires WEBCHAT_SESSION_SECRET plus basic and/or OIDC configuration.

→ Public authentication setup guide — env vars, GitHub OAuth, allowlists, production checklist.

See QUICKSTART.md and api-contract.md for install steps and the REST/WebSocket API.

Architecture

Browser UI  ←HTTP/WS→  web.ts adapter (in your fork)  →  NanoClaw router  →  agents
MCP server  ←REST──→  same adapter

packages/client   →  React SPA (dist/client/)
packages/adapter  →  channel adapter templates → copied into host src/
packages/cli      →  nanoclaw-webchat bin
packages/mcp      →  nanoclaw-webchat-mcp bin (bundled)
packages/shared   →  shared types (internal)
skills/add-webchat → /add-webchat install skill

Security

Two authentication models are supported:

Mode	Use case	Summary
Local (default)	Single operator on the same machine	Binds to `127.0.0.1`; `WEBCHAT_SECRET` embedded in served HTML
Public	Multiple users over a network	Login page, session cookies, optional OIDC/GitHub or shared password; see docs/public-auth.md

Do not bind to 0.0.0.0 or expose the port on the internet without enabling public auth, TLS, and an allowlist. Details: SECURITY.md.

Development

pnpm install
pnpm run typecheck
pnpm run test:coverage
pnpm run build
pnpm --filter @nanoclaw-webchat/client dev   # Vite → proxies /api to :3200

Test against a local NanoClaw fork without publishing:

cd ../your-nanoclaw-fork
pnpm add file:../nanoclaw-webchat
pnpm exec nanoclaw-webchat install

See CONTRIBUTING.md for branch flow, changesets, and monorepo layout.

Branches & releases

Branch	Role
`develop`	Integration — feature and fix PRs land here
`main`	Release — merging `develop` → `main` publishes to npm and creates a GitHub Release

Versioning uses Changesets. Release notes: CHANGELOG.md

License

See LICENSE.