286f6f43a7
Add complete Moltbot distributed cluster setup: - 6 documentation files (33KB) - Deployment tools and scripts - Configuration templates - Status dashboard See CLUSTER-CONFIG-SUMMARY.md for details.
Symbolic link
240 lines
7.0 KiB
Markdown
Symbolic link
240 lines
7.0 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Overview
|
|
|
|
Moltbot is a personal AI assistant platform with a Gateway-based architecture. The Gateway acts as a WebSocket control plane that connects channels (WhatsApp, Telegram, Slack, Discord, etc.) to agent sessions, tools, and companion apps (macOS, iOS, Android).
|
|
|
|
## Common Commands
|
|
|
|
### Development
|
|
```bash
|
|
# Build TypeScript to dist/
|
|
pnpm build
|
|
|
|
# Build and bundle Canvas A2UI vendor assets
|
|
pnpm canvas:a2ui:bundle
|
|
|
|
# Development loop with auto-reload on TS changes
|
|
pnpm gateway:watch
|
|
|
|
# Run TypeScript directly without building (via tsx)
|
|
pnpm dev
|
|
pnpm start
|
|
pnpm moltbot <command>
|
|
```
|
|
|
|
### UI
|
|
```bash
|
|
# Build the web UI
|
|
pnpm ui:build
|
|
# (automatically installs UI deps on first run)
|
|
```
|
|
|
|
### Testing
|
|
```bash
|
|
# Run all tests in parallel
|
|
pnpm test
|
|
|
|
# Run tests with coverage
|
|
pnpm test:coverage
|
|
|
|
# Watch mode for development
|
|
pnpm test:watch
|
|
|
|
# Run a single test file
|
|
pnpm test src/path/to/test.test.ts
|
|
|
|
# E2E tests (Docker-based)
|
|
pnpm test:e2e
|
|
|
|
# Live API tests
|
|
pnpm test:live
|
|
|
|
# Run all test suites
|
|
pnpm test:all
|
|
```
|
|
|
|
### Linting and Formatting
|
|
```bash
|
|
# Lint with oxlint
|
|
pnpm lint
|
|
|
|
# Lint and auto-fix issues
|
|
pnpm lint:fix
|
|
|
|
# Format check with oxfmt
|
|
pnpm format
|
|
|
|
# Format and write changes
|
|
pnpm format:fix
|
|
|
|
# Run all linters (TypeScript + Swift)
|
|
pnpm lint:all
|
|
pnpm format:all
|
|
```
|
|
|
|
### Protocol Generation
|
|
```bash
|
|
# Generate Gateway protocol schema
|
|
pnpm protocol:gen
|
|
|
|
# Generate Swift protocol bindings for iOS/macOS apps
|
|
pnpm protocol:gen:swift
|
|
|
|
# Check protocol schema is up-to-date
|
|
pnpm protocol:check
|
|
```
|
|
|
|
### Docker Tests
|
|
```bash
|
|
# Run all Docker-based E2E tests
|
|
pnpm test:docker:all
|
|
```
|
|
|
|
### Misc
|
|
```bash
|
|
# Sync plugin versions with main package
|
|
pnpm plugins:sync
|
|
|
|
# Check for release issues
|
|
pnpm release:check
|
|
```
|
|
|
|
## High-Level Architecture
|
|
|
|
### Gateway (`src/gateway/`)
|
|
|
|
The Gateway is the central WebSocket server that all clients connect to. It's started via `startGatewayServer()` in `src/gateway/server.impl.ts`.
|
|
|
|
Key responsibilities:
|
|
- **WebSocket server** - Serves WS clients on port 18789 (default)
|
|
- **Channel registry** - Manages channel plugins (WhatsApp, Telegram, etc.)
|
|
- **Session management** - Tracks agent sessions, routing, and state
|
|
- **Tool execution** - Handles requests for bash, browser, canvas, nodes, etc.
|
|
- **Event broadcast** - Distributes events to connected clients
|
|
- **HTTP endpoints** - Serves Control UI, OpenAI chat completions, OpenResponses
|
|
|
|
**Gateway Protocol (`src/gateway/protocol/`)**: Defines the WebSocket message schema (request/response, events, and typed payloads). All client-server communication follows this protocol.
|
|
|
|
### Channels (`src/channels/`)
|
|
|
|
Channel plugins connect messaging platforms to the Gateway. Each channel:
|
|
- Connects to its platform's API (WhatsApp via Baileys, Telegram via grammY, etc.)
|
|
- Normalizes incoming messages to Gateway protocol
|
|
- Handles message delivery, reactions, typing indicators
|
|
- Manages allowlists, mention gating, and group policies
|
|
|
|
**Channel registry (`src/channels/plugins/`)**: Loads and manages channel plugins. Core channels are built-in; additional channels are in `extensions/*/`.
|
|
|
|
### Agent Runtime (`src/agents/`)
|
|
|
|
The agent runtime manages AI agent sessions:
|
|
- **Pi agent integration** - Uses `@mariozechner/pi-ai` for agent execution
|
|
- **RPC mode** - Agent runs in separate process, communicates via stdio
|
|
- **Auth profiles** - Manages API keys and OAuth tokens with rotation
|
|
- **Bash tools** - Executes shell commands with PTY support and background process registry
|
|
- **Skills** - Loads workspace skills from `~/clawd/skills/`
|
|
|
|
**Agent Client Protocol (`src/acp/`)**: Implements the ACP protocol for agent communication, translating between Gateway events and ACP messages.
|
|
|
|
### Tools
|
|
|
|
**Browser (`src/browser/`)**: Chromium/Chrome automation via CDP (Chrome DevTools Protocol)
|
|
- Playwright-based session management
|
|
- Screenshot, navigation, interaction tools
|
|
- Profile management and extensions
|
|
|
|
**Canvas (`src/canvas-host/`)**: Live Canvas rendering via A2UI
|
|
- Pushes Canvas updates to connected nodes
|
|
- Handles A2UI evaluation and snapshots
|
|
|
|
**Bash (`src/agents/bash-tools.ts`)**: Shell command execution
|
|
- PTY-based command execution with `@lydell/node-pty`
|
|
- Background process management
|
|
- Environment variable handling
|
|
|
|
**Nodes**: Device-local actions (iOS/Android/macOS)
|
|
- Camera, screen recording, notifications
|
|
- Exposed via Gateway protocol when devices pair
|
|
|
|
### Configuration (`src/config/`)
|
|
|
|
- **Config file**: `~/.clawdbot/moltbot.json` (JSON5 + JSON schema validation)
|
|
- **Environment substitution**: Supports `${VAR}` syntax in config values
|
|
- **Legacy migrations**: Auto-migrates old config entries on startup
|
|
- **Session store**: SQLite-backed session state management
|
|
|
|
### Plugins (`src/plugins/`)
|
|
|
|
Extension system for channels, auth providers, and features:
|
|
- **Discovery**: Scans `extensions/` for plugin manifests
|
|
- **Loading**: Dynamic imports with dependency injection
|
|
- **Hooks**: Plugin hooks for event interception
|
|
- **HTTP registry**: Plugins can add HTTP routes
|
|
|
|
### CLI (`src/commands/`)
|
|
|
|
Command-line interface via Commander.js:
|
|
- `moltbot gateway` - Start the Gateway server
|
|
- `moltbot agent` - Send a message to the agent
|
|
- `moltbot channels` - Manage channels
|
|
- `moltbot configure` - Run configuration wizard
|
|
- `moltbot doctor` - Diagnose and fix issues
|
|
|
|
## Key Patterns
|
|
|
|
### Session Management
|
|
|
|
Sessions represent isolated agent conversations:
|
|
- `main` session for direct user interaction
|
|
- Group sessions for each group/chat
|
|
- Per-agent session isolation via routing
|
|
|
|
Session keys: `{channelId}/{peerId}` or `main` for direct CLI interaction.
|
|
|
|
### Message Routing
|
|
|
|
Inbound messages flow: `Channel -> Gateway -> Agent Session -> Tools -> Response -> Gateway -> Channel`
|
|
|
|
The Gateway routes messages to sessions based on:
|
|
- Channel and peer IDs
|
|
- Group membership
|
|
- Agent routing configuration
|
|
|
|
### Testing
|
|
|
|
- **Unit tests**: `src/**/*.test.ts` - Vitest with `test()` helper
|
|
- **E2E tests**: `vitest.e2e.config.ts` - Full integration tests
|
|
- **Live tests**: `vitest.live.config.ts` - Tests against real APIs
|
|
- Set `CLAWDBOT_LIVE_TEST=1` to enable live tests
|
|
|
|
### Extensions
|
|
|
|
Extensions live in `extensions/*/` and can provide:
|
|
- Additional channels (e.g., `extensions/discord/`, `extensions/whatsapp/`)
|
|
- Auth providers (e.g., `extensions/google-antigravity-auth/`)
|
|
- Tool extensions (e.g., `extensions/memory-lancedb/`)
|
|
|
|
Each extension has a `package.json` with a `moltbot.extensions` array pointing to entry modules.
|
|
|
|
## TypeScript Configuration
|
|
|
|
- Target: ES2022
|
|
- Module: NodeNext (ESM)
|
|
- Strict mode enabled
|
|
- Output: `dist/` directory
|
|
- Source files: `src/` directory
|
|
|
|
## Important File Locations
|
|
|
|
- `src/gateway/server.impl.ts` - Gateway server entry point
|
|
- `src/gateway/protocol/schema/` - Gateway protocol type definitions
|
|
- `src/channels/plugins/index.ts` - Channel plugin loader
|
|
- `src/agents/bash-tools.ts` - Bash tool implementation
|
|
- `src/browser/server.ts` - Browser control HTTP server
|
|
- `src/config/config.ts` - Config loading and validation
|
|
- `src/commands/agent.ts` - CLI agent command
|
|
- `moltbot.mjs` - CLI entry point
|