Project Introduction
Relevant source files
The following files were used as context for generating this wiki page:
Clawdbot is an AI-powered personal assistant and gateway system designed to bridge multiple messaging channels (such as WhatsApp, Discord, Telegram, and Slack) with advanced AI agents and specialized skills. It operates as a modular ecosystem where a central Gateway service manages communication routing, while modular "Skills" extend the core capabilities of the underlying AI models (referred to as Codex or Pi agents).
The project is built using TypeScript (ESM) and leverages Node.js (v22+) and Bun for runtime execution. It includes a multi-agent architecture where a main agent can spawn sub-agents to handle specific tasks, utilizing a comprehensive suite of tools for file system operations, web searching, browser control, and channel-specific actions.
Sources: CLAUDE.md:1-25, src/agents/system-prompt.ts:184-250, package.json:1-15
System Architecture
Clawdbot is structured around a central Gateway that serves as the integration point for messaging platforms and AI services. The architecture is designed to be platform-agnostic, supporting deployments on local machines, virtual machines (VMs), and containerized environments like Docker.
Core Components
| Component | Description |
|---|---|
| Gateway | The central daemon service that manages message routing, channel connections, and agent sessions. |
| Agents | AI entities (e.g., Codex, Pi) that process user requests and execute tools. |
| Skills | Modular packages containing instructions, scripts, and assets to provide specialized domain expertise. |
| Channels | Integration layers for external messaging platforms like Telegram, Discord, and Slack. |
| Nodes | Connected devices (Mac, iOS, Android) that can render content or execute local actions. |
Sources: CLAUDE.md:10-25, AGENTS.md:10-25, skills/skill-creator/SKILL.md:12-25, src/agents/system-prompt.ts:200-220
Infrastructure Diagram
This diagram illustrates the high-level relationship between the user, the Gateway, and the various execution environments.
Agent and Tooling System
The agent system is powered by a sophisticated system prompt that defines the operational boundaries and available tools for the AI. Agents can utilize a wide range of built-in tools to interact with the host system and external services.
Built-in Tools
Agents are equipped with a standard library of tools for various operations:
- File System:
read,write,edit,ls,grep, andfindfor workspace management. - Execution:
execfor shell commands andprocessfor managing background sessions. - Web:
web_searchandweb_fetchfor information retrieval. - Orchestration:
sessions_spawn,sessions_list, andsessions_sendfor multi-agent workflows. - Channel Actions:
messagefor proactive sending andcanvasfor displaying web content.
Sources: src/agents/system-prompt.ts:184-210, CLAUDE.md:120-135
Multi-Agent Workflow
The system supports the "Captain's Chair" pattern where a persistent orchestrator manages sub-agents. This allows for parallel processing and separation of concerns during complex tasks.
Project Structure
The repository follows a organized directory structure to separate core logic, extensions, and documentation.
src/: Core source code including CLI, infra, and channel implementations.extensions/: Workspace packages for optional plugins like MSTeams or Matrix.skills/: Modular skill packages (e.g.,coding-agent,canvas).apps/: Platform-specific applications for macOS, iOS, and Android.docs/: Documentation hosted on Mintlify.dist/: Built output for production distribution.
Sources: CLAUDE.md:5-15, package.json:18-60
Development and Contribution
Clawdbot uses a modern toolchain for development, prioritizing TypeScript and Bun for speed and reliability.
Development Commands
| Task | Command |
|---|---|
| Install | pnpm install |
| Build | pnpm build |
| Lint | pnpm lint |
| Test | pnpm test |
| Run CLI | pnpm clawdbot [command] |
Sources: CLAUDE.md:65-80, package.json:65-80
Contribution Guidelines
The project welcomes "AI-assisted" contributions. Maintainers emphasize that PRs should be focused and include clear descriptions of testing performed. Key contributors include Peter Steinberger (Benevolent Dictator) and specialized maintainers for the Discord/Slack and Telegram/API subsystems.
Sources: CONTRIBUTING.md:1-40
Summary
Clawdbot is a comprehensive framework for building and deploying intelligent AI assistants across multiple messaging platforms. By combining a robust gateway architecture with a modular skill system and advanced tool integration, it enables developers to create specialized agents that can interact with the real world, manage complex workflows, and provide a seamless user experience across different devices and communication channels.