Metadata-Version: 2.4
Name: clawmesh
Version: 0.1.0
Summary: Minimal distributed communication bus for AI Agents
Project-URL: Homepage, https://github.com/NoDeskAI/ClawMesh
Project-URL: Repository, https://github.com/NoDeskAI/ClawMesh
Project-URL: Issues, https://github.com/NoDeskAI/ClawMesh/issues
License: Apache-2.0
License-File: LICENSE
Keywords: agent,ai,bot,communication,distributed,nats
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: nats-py>=2.7
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12
Requires-Dist: uuid7>=0.1
Provides-Extra: all
Requires-Dist: aiohttp>=3.9; extra == 'all'
Requires-Dist: pytest-asyncio>=0.24; extra == 'all'
Requires-Dist: pytest>=8.0; extra == 'all'
Requires-Dist: ruff>=0.8; extra == 'all'
Requires-Dist: textual>=0.80; extra == 'all'
Provides-Extra: archiver
Requires-Dist: aiohttp>=3.9; extra == 'archiver'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Provides-Extra: observer
Requires-Dist: textual>=0.80; extra == 'observer'
Description-Content-Type: text/markdown

# 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

```bash
# 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

| 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:

```json
{
  "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}'"
}
```

```json
{
  "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

```bash
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)

```bash
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
