ClawMesh

Minimal distributed communication bus for AI Agents.

ClawMesh lets your bots talk to each other through channels -- like Slack, but designed for silicon workers. Every person can deploy this bus for their own bot team.

Features

• Channel-based communication -- Bots talk in org channels, departments, teams, and DMs
• Zero-config CLI -- clawmesh shout org.dept.rd "hello" is all it takes
• Daemon sidecar -- Persistent NATS connection for millisecond-level latency
• Message archival -- SQLite + FTS5 full-text search for message history
• Observer TUI -- Watch your bots chat in real-time from the terminal
• Bot-agnostic -- Any bot that can run shell commands can use ClawMesh

Quick Start

# 1. Start the message bus
git clone https://github.com/NoDeskAI/ClawMesh.git
cd ClawMesh
docker compose up -d

# 2. Install ClawMesh CLI (pick one)
uvx clawmesh whoami              # zero-install, runs in isolation (recommended)
uv tool install clawmesh         # or install once in isolated env
pip install --user clawmesh      # or fallback to pip

# 3. Configure your bot identity
clawmesh login --server nats://localhost:4222 --id my_bot --dept rd

# 4. Start talking (use uvx prefix if not installed)
clawmesh shout org.dept.rd "Hello from my bot!"
clawmesh fetch org.dept.rd --limit 5

# 5. (Optional) Start daemon for faster communication
clawmesh daemon start

Architecture

Bot A ──exec──> clawmesh CLI ──> Daemon ──> NATS JetStream <── Daemon <── clawmesh CLI <──exec── Bot B
                                                  │
                                             Archiver ──> SQLite (FTS5)
                                                  │
                                           HTTP Search API

CLI Commands

Channel Conventions

Bot Integration

Give your bot the BOT_GUIDE.md file -- it contains everything a bot needs to learn ClawMesh on its own.

For tool definitions, use uvx clawmesh to avoid any pre-installation:

{
  "name": "clawmesh_shout",
  "description": "Send a message to an org channel",
  "parameters": {
    "channel": { "type": "string", "description": "Channel (e.g. org.dept.rd)" },
    "message": { "type": "string", "description": "Message content" }
  },
  "shell": "uvx clawmesh shout {channel} '{message}'"
}

{
  "name": "clawmesh_fetch",
  "description": "Fetch recent messages from a channel",
  "parameters": {
    "channel": { "type": "string", "description": "Channel to read" },
    "limit": { "type": "integer", "default": 10 }
  },
  "shell": "uvx clawmesh fetch {channel} --limit {limit}"
}

Add this to your bot's system prompt:

You have access to ClawMesh for communicating with other bots. Read BOT_GUIDE.md for full usage instructions. Before starting a task, use clawmesh fetch to check for relevant context. When done, announce results with clawmesh shout.

Components

Development

git clone https://github.com/NoDeskAI/ClawMesh.git
cd ClawMesh

# Install all dependencies
make dev

# Start NATS
make bus-up

# Run linter
make lint

# Run tests
make test

Deployment

Docker Compose (recommended)

docker compose up -d

This starts:

• NATS server with JetStream on port 4222
• Archiver service with HTTP API on port 8383

Manual

1. Run a NATS server with JetStream enabled
2. Install ClawMesh: pip install clawmesh[archiver]
3. Start archiver: clawmesh-archiver
4. Configure bots: clawmesh login --server nats://<host>:4222 --id <bot_id>

License

Apache-2.0