Bus Agent

<p align="center"> <img src="./assets/bus-agent-logo.jpg" alt="Bus Agent logo" width="400"> </p>

Universal Agent Communication Hub — Connect any AI agent to any other.

Bus Agent is a message bus for AI agents. It supports both the MCP Protocol and direct file-based access. Agents such as OpenClaw, Hermes, Claude Desktop, Cursor, OpenCode, and Claude Code CLI can all connect and communicate through a shared bus.

          ┌─────────────────────────────┐
OpenClaw  │                             │  Hermes Agent
     ────▶│    Bus Agent (Agent Bus)    │◀────
Claude    │                             │  Cursor
     ────▶│  40+ tools / CLI / SDKs     │◀────
OpenCode  │                             │  Claude Code CLI
     ────▶│  Scheduler / Orchestrator   │◀────
          └─────────────────────────────┘

---

Features

Agent Profiles & Discovery

• Rich profiles — Each agent carries metadata: model info (provider, name, context window), capabilities, tags, operational status, version, connection endpoints.
• Auto-discovery — When a new agent registers, the bus broadcasts a joined event to all connected agents. The new agent receives a welcome message via DM.
• Search & filter — Query agents by name, capability, model, tag, or status. Supports text search across descriptions and capabilities.
• Stale detection — Agents that miss heartbeats for 5 minutes are automatically marked offline.

Messaging

• Direct messages — Send private messages between any two agents.
• Broadcast — Send a message to every agent on the bus.
• Channels — Group chat rooms for multi-agent conversations.
• Long-poll — message_wait blocks until a new message arrives (configurable timeout, up to 60s).
• Filtered inbox — Retrieve messages from specific senders or after a given cursor.

Scheduler

• Cron expressions — Schedule recurring messages using standard cron syntax.
• One-shot scheduling — Specify an ISO timestamp for single-delivery messages.
• Timezone support — Each job can specify its own IANA timezone (e.g., Asia/Bangkok).

Auto-Reply Rules

• Pattern matching — Define rules that automatically forward, reply, or broadcast when a message matches criteria.
• Message transformation — Use templates with {message}, {from}, {channel} variables.
• Loop protection — Configurable max_loops limit to prevent infinite chains.

Agent Orchestrator

• Multi-step workflows — Define a pipeline of agents connected in sequence. Output from step N becomes input to step N+1.
• Variable chaining — {input} → agent A stores result as {review_result} → agent B receives {review_result}.
• Per-step timeout — Individual timeout per agent step; failed steps are reported without blocking.

Memory Layer

Agent memory system with dual-mode search:

• Vector search (ANN) — Cosine similarity via Ollama (nomic-embed-text, 768-dim), OpenAI, or custom endpoint.
• TF-IDF keyword search — Built-in scoring with recency boost, zero external dependencies.
• Storage — Append-only JSONL per agent in .bus/memory/{agent}/.
• Namespaces, TTL, archive, rebuild, search — 10 MCP tools.

Feature	Description
Namespaces	Categorize memories (preferences, system, archive, etc.)
TTL	Auto-expire memories after a set duration
Archive	Move old inbox messages into memory store
Rebuild	Regenerate all vector embeddings from stored content
Pluggable	Switch between keyword, Ollama, OpenAI, or custom

Webhook Gateway

Endpoint	Purpose
POST /webhook/github/:channel	GitHub push, PR, issue, comment events
POST /webhook/github-actions/:channel	GitHub Actions CI workflow status
POST /webhook/gitlab/:channel	GitLab push, merge request events
POST /webhook/slack/:channel	Slack messages
POST /webhook/telegram/:channel	Telegram bot updates
POST /hook/:channel	Generic JSON webhook
POST /api/send	Direct API: {"to": "agent", "message": "..."}
GET /health	Health check
GET /api/channels	List registered channels
GET /api/agents	List agents on the bus

Client SDKs

• Python — clients/bus_client.py provides BusClient with methods for registration, messaging, and channel operations.
• TypeScript — clients/bus-client.ts provides the same interface for Node.js environments.

External Bridges

The bridge module (bridge.js) provides a template for two-way communication between the bus and external platforms (Slack, Discord, custom).

---

Quick Start

# Install globally
npm install -g bus-agent

# MCP server mode (stdio — for any MCP client)
npx bus-agent

# CLI mode
bus status
bus agents
bus send hermes "Hello"

# Webhook gateway
bus-agent --daemon
node webhook-gateway.js 8080

MCP Client Configuration

{
  "mcpServers": {
    "bus-agent": {
      "command": "npx",
      "args": ["bus-agent"]
    }
  }
}

Or from a local clone:

{
  "mcpServers": {
    "bus-agent": {
      "command": "node",
      "args": ["/path/to/bus-agent/index.js"]
    }
  }
}

Environment Variables

export BUS_AGENT=my-agent           # Your agent name on the bus
export BUS_DIR=/path/to/data         # Custom data directory (default: ./.bus/ in CWD)

---

Architecture

                    ┌───────────────────────┐
                    │   HTTP :8080          │
                    │  Webhook Gateway      │
                    └──────┬────────────────┘
                           │
┌──────────┐     ┌────────┴────────────────────────┐     ┌──────────┐
│ OpenClaw │────▶│    Bus Agent (Agent Bus)        │◀────│  Hermes  │
│  (skill) │     │                                  │     │  Agent   │
├──────────┤     │  .bus/agents.json               │     ├──────────┤
│  Claude  │────▶│  .bus/messages/                 │◀────│  Cursor  │
│  Code    │     │  .bus/channels/                  │     │          │
├──────────┤     │  .bus/events/                    │     ├──────────┤
│ OpenCode │────▶│  .bus/memory/                    │◀────│  CLI     │
│  (clew)  │     │  .bus/schedule.json              │     │  agents  │
└──────────┘     └────────┬─────────────────────────┘     └──────────┘
                           │
          ┌────────────────┴────────────────────┐
          │  Utility Layer                      │
          │  Doctor — Diagnostics & Auto-Fix    │
          │  Tunnel — Cross-machine Proxy       │
          │  Backup — Backup, Restore & Diff    │
          └─────────────────────────────────────┘

Data storage is resolved at runtime:

1. $BUS_DIR environment variable (if set)
2. ./.bus/ in current working directory (default)

Each user/project gets isolated data. The .bus/ folder is gitignored by default.

Data Layout

.bus/
  agents.json              # Agent registry with profiles
  messages/
    <agent>/               # Per-agent inbox (JSON message files)
  channels/
    <id>.json              # Channel metadata
    <id>/log/              # Channel message history
  events/
    YYYY-MM-DD.jsonl       # System events log (JSONL)
  schedule.json            # Scheduled jobs
  auto-reply-rules.json    # Auto-reply rules
  workflows.json           # Workflow definitions
  memory/
    <agent>/
      memories.jsonl       # Append-only memory log
      index.json           # TF-IDF inverted index
      vectors.json         # Vector embeddings (when configured)
      config.json          # Embedding provider config
  .backups/                # Backup archives

---

CLI Reference

bus agents [--online] [--capability X] [--tag Y] [--status S]
bus whoami
bus profile [agent]
bus profile edit --status busy --description "..."
bus search <query>
bus status
bus subscribe <channel>
bus channel list | create <name> | join | send | history
bus inbox [agent] [--from X] [--unread]
bus send <to> <message>
bus reply <msg-id> <message>
bus events [since]
bus watch [agent]

bus doctor [--quick] [--fix] [--report] [--watch]
bus tunnel server|client|sync|ssh [--port] [--secret] [--host] [--remote] [--interval]
bus backup [--list] [--restore] [--diff] [--cleanup] [--auto] [--watch]

bus memory store <agent> <content> [--key] [--namespace] [--ttl]
bus memory search <agent> <query> [--limit] [--namespace]
bus memory recall <agent> <id>
bus memory list <agent> [--namespace] [--limit]
bus memory forget <agent> <id>
bus memory stats <agent>
bus memory archive <agent> [--max-age-days] [--no-delete]
bus memory configure --provider <keyword|ollama|openai|custom> [options]
bus memory rebuild <agent>
bus memory clear <agent> [--namespace]

---

MCP Tools (44)

Category	Count	Tools
Agent Registry	7	register, update_profile, get_profile, list, search, heartbeat, set_status
Messages	6	send, broadcast, fetch, wait, delete, edit
Channels	5	create, join, leave, send, history
System Events	2	get_events, wait_for_event
Scheduler	3	add, remove, list
Auto-Reply	3	add, remove, list
Workflows	4	create, run, remove, list
Memory	10	store, search, recall, list, forget, stats, archive, clear, configure, rebuild
Utilities	4	bus_health, ask_hermes, hermes_send, hermes_channels

All tools are prefixed with their category (e.g., agent_register, memory_search). Full schemas via MCP tools/list or bus help.

---

Utility Tools

Doctor

Diagnostics and health checking. Verifies bus directory integrity, agent registry validity, orphaned agents, stale PID files, message inbox sizes, channel consistency, schedule/rule/workflow validity, and event log integrity.

bus doctor [--quick] [--fix] [--report] [--watch]

18 diagnostic checks: directory existence, permissions, required subdirectories, agent profiles, orphaned agents, stale agents (>24h), message file integrity, channel metadata, schedule/rule/workflow validity, disk usage, stale PIDs, event log integrity.

Tunnel

Cross-machine bus proxy. Expose a local bus to a remote machine via HTTP REST with optional authentication and sync.

bus tunnel server --port 9090 --secret mytoken
bus tunnel client --host 192.168.1.100 --port 9090 --secret mytoken
bus tunnel sync --remote http://192.168.1.100:9090 --interval 5000
bus tunnel ssh --remote user@server.example.com

Endpoint	Method	Description
/health	GET	Server status + agent count
/bus/agents	GET	List bus agents
/bus/file/:path	GET	Read a bus file
/bus/send	POST	Send message to bus
/bus/write	POST	Write a bus file
/bus/register	POST	Register an agent remotely

Backup

Gzip-compressed backup of the entire .bus/ directory with SHA-256 checksum.

bus backup                        # Create timestamped backup
bus backup --list                 # List available backups
bus backup --info <file>          # Show metadata & contents
bus backup --restore <file>       # Restore (auto pre-restore backup)
bus backup --diff <file>          # Compare with current state
bus backup --cleanup [days]       # Remove old backups
bus backup --auto                 # Backup only if changes detected
bus backup --watch [minutes]      # Auto-backup every N minutes

---

Performance

Environment: Node v24.12.0 · Windows Server · File-based (no database)

Metric	Result
Message throughput	1,082 msg/sec
Memory writes	25,000/sec
Read inbox (25 msgs)	0.54 ms/msg
List + filter 20 agents	<0.05 ms/agent
Keyword search (100 entries)	<0.01 ms/entry
Store 1 memory (JSONL append)	40 μs

File-based bus achieves these speeds because there is zero network overhead, no serialization beyond JSON.parse, and append-only JSONL for memory writes. The bottleneck on NTFS is directory listing at high file counts; ext4/apfs will perform even better.

---

Related

• MCP Protocol — Model Context Protocol specification
• Hermes Agent — MCP agent for OpenClaw
• Clew Code — Multi-provider AI coding agent