Tech World Bot (Clawd)

AI tutor bot for Tech World - a multiplayer game where players learn programming together.

What it does

Clawd joins LiveKit rooms as a participant and responds to chat messages using Claude AI. It provides friendly, encouraging coding help to players.

Quick Start

1. Install dependencies:

   npm install

2. Configure environment:

   cp .env.example .env
   # Edit .env with your credentials

3. Run locally:

   npm run dev

Environment Variables

Variable	Description
LIVEKIT_URL	LiveKit server WebSocket URL
LIVEKIT_API_KEY	LiveKit API key
LIVEKIT_API_SECRET	LiveKit API secret
ANTHROPIC_API_KEY	Anthropic API key for Claude

How it works

1. Bot registers as a LiveKit Agent worker
2. The Flutter client calls the retrieveLiveKitToken Cloud Function, which embeds a RoomAgentDispatch in the token's RoomConfiguration — this ensures the bot is dispatched whether the room is new or already exists
3. Bot joins the room as participant bot-claude
4. Players send messages on the chat data channel topic
5. Bot calls Claude API and responds on chat-response topic
6. All players in the room see the response
7. For spell casting, the client sends on oracle-request (targeted); the bot interprets the cast and replies on oracle-response using a kind discriminator ('spell_cast', 'spell_combo', …)

Tech Stack

• Runtime: Node.js 20+ in Docker, deployed on OCI (149.118.69.221)
• Framework: @livekit/agents — connects to self-hosted LiveKit at wss://livekit.imagineering.cc
• AI: Claude API via @anthropic-ai/sdk
• Language: TypeScript

Deploy

Production deploys via the imagineering-infra repo:

cd ~/git/orgs/imagineering/imagineering-infra
./scripts/deploy-to.sh 149.118.69.221 tech-world-bots

This decrypts secrets, rsyncs source, builds the Docker image on the VPS, and restarts the tw-clawd / tw-gremlin containers. See CLAUDE.md for verification steps after a deploy.

Scripts

Script	Description
npm run dev	Run with hot reload (development)
npm run build	Compile TypeScript to JavaScript
npm start	Run compiled version (production)
npm run lint	Run ESLint
npm run typecheck	Type check without emitting

Related

• tech_world - Flutter client app
• tech_world_firebase_functions - Token generation

License

MIT