claw3d/docs/integrations/agent-bus.md

Agent Bus Integration

Visualize AI coding sessions in Claw3D's retro office — without OpenClaw.

Agent Bus is an open-source event routing system that bridges AI coding agents (Claude Code, Gemini, Codex, etc.) to Claw3D. Agents appear in the 3D office, animate when working, and go idle between tasks. Zero inference cost — pure data routing.

How It Works

AI coding session → hook fires → Agent Bus hub → gateway :18789 → Claw3D renders in 3D

Agent Bus includes an OpenClaw-compatible gateway that speaks the same WebSocket protocol Claw3D already uses. No Claw3D code changes needed — just point GATEWAY_URL to the Agent Bus gateway.

Architecture

┌───────────────────────────────────────────┐
│ Producers (any machine)                    │
│                                            │
│ Claude Code → PostToolUse hook → POST :4000│
│ Gemini CLI  → hook/script    → POST :4000 │
│ Any agent   → curl           → POST :4000 │
└────────────────────┬──────────────────────┘
                     │ HTTP POST /events
                     ▼
┌──────────────────────────────────────────┐
│ Agent Bus Hub (:4000)                     │
│ Validates → broadcasts → logs to JSONL   │
└────────────────────┬─────────────────────┘
                     │ WebSocket
                     ▼
┌──────────────────────────────────────────┐
│ Agent Bus Gateway (:18789)               │
│ OpenClaw protocol v2                     │
│ In-memory agent registry                 │
│ 10 RPC methods (connect, agents.list...) │
└────────────────────┬─────────────────────┘
                     │ WebSocket (OpenClaw frames)
                     ▼
┌──────────────────────────────────────────┐
│ Claw3D (:3000)                           │
│ Connects via GATEWAY_URL                 │
│ Renders agents in 3D retro office        │
└──────────────────────────────────────────┘

Quick Start

Prerequisites

• Node.js 18+
• Claw3D running on :3000

Setup (5 minutes)

# Clone Agent Bus
git clone https://github.com/emiliovos/agent-bus.git
cd agent-bus
npm install

# Start the hub and gateway
npm run dev:all

This starts:

• Hub on :4000 (event routing)
• Gateway on :18789 (OpenClaw protocol)

Connect Claw3D

Point Claw3D's gateway URL to Agent Bus:

# In your Claw3D .env or environment:
GATEWAY_URL=ws://localhost:18789

Restart Claw3D. It will connect to the Agent Bus gateway instead of OpenClaw.

Send Your First Event

curl -X POST http://localhost:4000/events \
  -H "Content-Type: application/json" \
  -d '{"agent":"my-agent","project":"demo","event":"session_start"}'

# Agent appears in the 3D office!

curl -X POST http://localhost:4000/events \
  -d '{"agent":"my-agent","project":"demo","event":"tool_use","tool":"Edit","file":"app.ts"}'

# Agent animates "working" for 5 seconds

Connect Claude Code Hooks

Agent Bus includes hook scripts that fire on every Claude Code tool use:

# Copy hooks
cp agent-bus/scripts/hook-post-tool-use.sh ~/.agent-bus/
cp agent-bus/scripts/hook-session-event.sh ~/.agent-bus/
chmod +x ~/.agent-bus/*.sh

# Set environment
export AGENT_BUS_AGENT="my-name"
export HUB_URL="http://localhost:4000"

Add to .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [{ "type": "command", "command": "bash ~/.agent-bus/hook-post-tool-use.sh" }],
    "Stop": [{ "type": "command", "command": "bash ~/.agent-bus/hook-session-event.sh end" }]
  }
}

Every tool use in Claude Code now appears as agent activity in Claw3D.

Gateway Protocol Compatibility

The Agent Bus gateway implements OpenClaw protocol v2:

RPC Method	Supported	Notes
connect	Yes	Returns hello-ok with agent snapshot
health	Yes	{ ok: true }
agents.list	Yes	Returns registered agents from hub events
config.get	Yes	Agent identity and configuration
sessions.list	Yes	Active sessions with message counts
sessions.preview	Yes	Recent chat messages (ring buffer, last 100)
status	Yes	Agent activity status
exec.approvals.get	Yes	Returns empty (no exec approval system)
chat.send	Partial	Logged, not delivered to agents (v1)
chat.abort	Partial	Logged, not delivered (v1)

Events Emitted

Event	When
agent (lifecycle)	Agent starts/stops working
chat (activity)	Tool use, task completion
presence	Agent registry changes
tick	Keepalive every 30 seconds

Remote Access

Agent Bus supports Cloudflare Tunnel for secure remote access:

# Automated setup
bash scripts/setup-cloudflare-tunnel.sh

This exposes the hub and Claw3D via HTTPS with service token authentication. Agents on remote machines (VPS, other PCs) can send events through the tunnel.

Event Schema

interface AgentEvent {
  ts?: number;        // Unix timestamp ms (auto-added if missing)
  agent: string;      // Agent identifier (e.g., "backend-dev")
  project: string;    // Project namespace (e.g., "my-app")
  event: string;      // "session_start" | "session_end" | "tool_use" | "task_complete" | "heartbeat"
  tool?: string;      // Tool name for tool_use events
  file?: string;      // File path for file operations
  message?: string;   // Human-readable description
}

Key Differences from OpenClaw

Feature	OpenClaw	Agent Bus
Cost	API tokens per inference	$0 (pure routing)
Agents	LLM-powered	Event-driven (any source)
Setup	Gateway + API keys	npm install && npm run dev:all
Chat interaction	Bidirectional	View-only (v1)
Agent sources	OpenClaw agents only	Any (Claude Code, Gemini, cron, etc.)

Links

• Agent Bus Repository
• Getting Started Guide
• API Reference
• Hook Integration Guide