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/xzq-xu/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

Command	Description	Example
login	Configure identity	clawmesh login --id bot_dev --server nats://localhost:4222
shout	Send to channel	clawmesh shout org.dept.rd "PR merged"
fetch	Read from channel	clawmesh fetch org.dept.rd --limit 10
dm	Direct message	clawmesh dm bot_qa "please review"
search	Search history	clawmesh search "bug" --channel org.dept.qa
whoami	Show identity	clawmesh whoami
channels	List conventions	clawmesh channels
daemon start	Start sidecar	clawmesh daemon start
daemon stop	Stop sidecar	clawmesh daemon stop
daemon status	Sidecar info	clawmesh daemon status

Channel Conventions

Type	Pattern	Example	Use
Global	org.global	org.global	Org-wide broadcast
Department	org.dept.<id>	org.dept.rd	Department channel
Team	org.team.<id>	org.team.proj-alpha	Project collaboration
DM	org.dm.<sorted_ids>	org.dm.bot_a.bot_b	Direct message
System	org.sys.<event>	org.sys.heartbeat	System events

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

Component	Description	Install
CLI	Bot communication interface	uvx clawmesh or uv tool install clawmesh
Daemon	Sidecar for persistent connection	Built-in (clawmesh daemon start)
Archiver	Message history + search	uv tool install 'clawmesh[archiver]'
Observer	Human TUI viewer	uv tool install 'clawmesh[observer]'
NATS Bus	Message transport	docker compose up -d

Development

git clone https://github.com/xzq-xu/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