A lightweight multi-agent verison of OpenClaw built on the swarms framework # ClawSwarm ClawSwarm provides programmatic access to Claude-based agents and a unified messaging gateway for production integrations. It is designed for teams that need consistent agent orchestration and multi-channel message aggregation behind a single, secure API. --- ## Overview ClawSwarm consists of two main components: 1. **Claude agent utilities** — Run Claude Code agents with configurable identity (name, description, system prompt) and tasks. Supports synchronous execution, async, and streaming. Suitable for automation pipelines, batch processing, and embedding agent workflows into existing services. 2. **Messaging Gateway** — A gRPC service that aggregates incoming messages from Telegram, Discord, and WhatsApp into a single schema. Clients poll or stream messages over one protocol, with optional TLS. Intended for bot backends, support tooling, and unified inbox implementations. Both components are library- and service-friendly: no mandatory UI, configuration via environment variables and code, and interfaces that integrate with standard Python async runtimes and gRPC tooling. --- ## Requirements - Python 3.10+ - [Claude Code CLI](https://docs.anthropic.com/en/docs/build-with-claude/claude-code) (for agent utilities) and appropriate API access - For the gateway: bot tokens or API credentials for the platforms you enable (Telegram, Discord, WhatsApp) --- ## Installation Clone the repository and install dependencies: ```bash git clone https://github.com/YOUR_ORG/ClawSwarm.git cd ClawSwarm pip install -r requirements.txt ``` For editable development installs, install the package in place: ```bash pip install -e . ``` *(Requires a `pyproject.toml` or `setup.py` in the repository.)* --- ## Claude Agent Utilities The public API is in `claw_swarm.tools`. ### One-off run (blocking) ```python from claw_swarm import run_claude_agent responses = run_claude_agent( name="CodeReviewer", description="Reviews Python code for style and correctness.", prompt="Respond in bullet points. Flag security issues.", tasks="Review the authentication logic in auth.py", ) for text in responses: print(text) ``` ### Async and streaming ```python import asyncio from claw_swarm import run_claude_agent_async, stream_claude_agent # Collect all responses asynchronously async def run(): texts = await run_claude_agent_async( name="Summarizer", description="Summarizes long documents.", prompt="Keep summaries under 200 words.", tasks="Summarize the attached report.", ) return texts # Or stream assistant text as it arrives async def stream(): async for block in stream_claude_agent( name="Helper", description="Answers questions concisely.", prompt="Be precise and cite sources when possible.", tasks="What are the main risks in this contract?", ): print(block, end="") asyncio.run(stream()) ``` Agents use the Claude Code preset (e.g. read, write, edit, bash, grep) and a configurable turn limit. Each call is a new session; no conversation history is retained across calls. --- ## Messaging Gateway The gateway exposes a gRPC API for polling and streaming messages from Telegram, Discord, and WhatsApp. All messages are normalized to a single `UnifiedMessage` schema (id, platform, channel, sender, text, attachments, timestamp). ### Configuration Configure via environment variables. Omit a platform’s token to disable that adapter (it will return no messages). | Variable | Description | |----------|-------------| | `TELEGRAM_BOT_TOKEN` | Telegram Bot API token | | `DISCORD_BOT_TOKEN` | Discord bot token | | `DISCORD_CHANNEL_IDS` | Comma-separated Discord channel IDs to read | | `WHATSAPP_ACCESS_TOKEN` | WhatsApp Cloud API access token | | `WHATSAPP_PHONE_NUMBER_ID` | WhatsApp phone number ID | | `GATEWAY_HOST` | Bind host (default: `[::]`) | | `GATEWA