Bus Agent

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 (43)

| Category | Count | Tools | |----------|-------|-------| | Agent Registry | 7 | register, update_profile, get_profile, list, search, heartbeat, set_status | | Messages | 5 | send, broadcast, fetch, wait, delete | | 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 [email protected]

| 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