bus-agent 2.3.4 → 2.3.6

package/{.env.coco → .env.bus}

@@ -2,7 +2,7 @@
 # Generated by CoCo Config Wizard
 
 # Your agent name on the bus
-COCO_AGENT=agent
+BUS_AGENT=agent
 
 # Path to the CoCo bus directory
 COCO_BUS_DIR=E:\_system\.openclaw\workspace\repos\mcp-coco\.bus

package/AGENTS.md

@@ -1,8 +1,8 @@
-# MCP CoCo — AGENTS.md
+# MCP Bus — AGENTS.md
 
 ## Identity
 
-MCP CoCo is a bridge agent that connects OpenClaw and Hermes Agent. It lives in the workspace at `mcp-coco/`.
+MCP Bus is a bridge agent that connects OpenClaw and Hermes Agent. It lives in the workspace at `mcp-coco/`.
 
 ## Files
 
@@ -21,17 +21,17 @@ MCP CoCo is a bridge agent that connects OpenClaw and Hermes Agent. It lives in
 - **`ask_hermes`** — Talk to Hermes. Supports multi-turn via `session_key`.
 - **`hermes_send`** — Send messages through Hermes to chat platforms.
 - **`hermes_channels`** — List available Hermes channels.
-- **`coco_health`** — Check bridge + Hermes health.
+- **`bus_health`** — Check bridge + Hermes health.
 
 ## Operational Notes
 
-- Daemon mode writes PID to `.coco-daemon.pid`
+- Daemon mode writes PID to `.bus-daemon.pid`
 - Hermes session keys stored in `.sessions/` directory
-- Logs go to `coco-daemon.log` in daemon mode
+- Logs go to `bus-daemon.log` in daemon mode
 - Daemon auto-starts Hermes MCP backend (`hermes mcp serve --accept-hooks`)
 
 ## Related
 
-- [MCP CoCo README](./README.md)
+- [MCP Bus README](./README.md)
 - [MCP Protocol Spec](https://modelcontextprotocol.io)
 - [Hermes Agent](https://github.com/NousResearch/hermes-agent)

package/README.md

@@ -1,15 +1,15 @@
-# MCP CoCo
+# Bus Agent
 
 **Universal Agent Communication Hub** — Connect any AI agent to any other.
 
 [![GitHub](https://img.shields.io/badge/GitHub-ClewCode%2Fbus--agent-blue)](https://github.com/ClewCode/bus-agent)
 
-MCP CoCo is a **message bus** for AI agents. It supports both the [MCP Protocol](https://modelcontextprotocol.io) (Model Context 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.
+Bus Agent is a **message bus** for AI agents. It supports both the [MCP Protocol](https://modelcontextprotocol.io) 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
-     ────▶│    MCP CoCo (Agent Bus)     │◀────
+     ────▶│    Bus Agent (Agent Bus)    │◀────
 Claude    │                             │  Cursor
      ────▶│  40+ tools / CLI / SDKs     │◀────
 OpenCode  │                             │  Claude Code CLI
@@ -23,60 +23,59 @@ OpenCode  │                             │  Claude Code CLI
 
 ### 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.
+- **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.
+- **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.
-
-### CLI (coco-cli.js)
-
-```
-node coco-cli.js agents [--online] [--capability X] [--tag Y] [--model Z] [--status S]
-node coco-cli.js profile [agent]
-node coco-cli.js profile edit --status busy --description "..."
-node coco-cli.js search <query>
-node coco-cli.js status
-node coco-cli.js subscribe <channel>
-node coco-cli.js channel list|create <name>|join|send|history
-node coco-cli.js inbox [agent] [--from X] [--unread]
-node coco-cli.js events [since]
-node coco-cli.js watch [agent]
-node coco-cli.js doctor [--quick] [--fix]
-node coco-cli.js tunnel server|client|sync|ssh [options]
-node coco-cli.js backup [--list|--restore|--diff|--cleanup]
-```
+- **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: `0 9 * * 1-5` sends to a channel or agent every weekday at 09:00.
-- **One-Shot Scheduling** — Specify an ISO timestamp (`at`) for single-delivery messages. The job is automatically disabled after firing.
-- **Timezone Support** — Each job can specify its own IANA timezone (e.g., `Asia/Bangkok`).
+- **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 (by sender, text content, regex, or metadata fields).
-- **Message Transformation** — Use templates with `{message}`, `{from}`, `{channel}` variables.
-- **Loop Protection** — Each rule has a configurable `max_loops` limit to prevent infinite chains.
+- **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 via variable substitution.
-- **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 the caller indefinitely.
+- **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, pull request, issue, comment events |
+| `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 |
@@ -87,146 +86,37 @@ node coco-cli.js backup [--list|--restore|--diff|--cleanup]
 | `GET /api/channels` | List registered channels |
 | `GET /api/agents` | List agents on the bus |
 
-### External Bridges
-
-A bridge module (`bridge.js`) provides a template for two-way communication between the bus and external platforms. Supports Slack, Discord, and custom generic bridges via HTTP listener. Channel mapping externalizes bus channels to platform-specific channels.
-
 ### Client SDKs
 
-- **Python** — `clients/coco_client.py` provides `CoCoClient` with methods for registration, messaging, and channel operations.
-- **TypeScript** — `clients/coco-client.ts` provides the same interface for Node.js environments.
-
-### Config Wizard
-
-```
-node setup.js              # Interactive wizard
-node setup.js --quick      # Quick setup with defaults
-node setup.js list         # Display config examples
-```
-
-Generates `.mcp.json` configuration files for OpenCode, Claude Code, and Cursor, along with environment files (`.env.coco`) and shell aliases (`coco-aliases.sh`).
-
-### OpenClaw Native Integration
-
-The `coco-tool.js` wrapper provides direct file-based access to the bus without requiring an MCP transport layer:
-
-```bash
-node coco-tool.js agent_register '{"name":"agent","capabilities":["chat","code"]}'
-node coco-tool.js agent_search '{"query":"code"}'
-node coco-tool.js message_send '{"from":"agent","to":"hermes","message":"Hello"}'
-node coco-tool.js workflow_run '{"workflow_id":"review-and-deploy","input":"..."}'
-```
-
-### Bus Doctor
-
-Diagnostics and health checking for the CoCo bus. 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.
-
-```bash
-node doctor.js                    # Full diagnostic report
-node doctor.js --quick            # Summary only
-node doctor.js --fix              # Auto-fix minor issues (missing dirs, stale PIDs, corrupted files)
-node doctor.js --report           # Save report to .bus/diagnostic-report.json
-node doctor.js --watch            # Watch mode (check every 30s)
-
-# Via CLI
-node coco-cli.js doctor --fix
-```
-
-18 checks are performed:
-- Bus directory existence & permissions
-- Required subdirectories (messages, channels, events)
-- Agent registry — profiles, missing fields, stale agents (>24h)
-- Orphaned agents (registered but never active, >7 days)
-- Message inbox sizes & file integrity
-- Channel metadata & log file integrity
-- Schedule file validity
-- Auto-reply rule validity
-- Workflow definition validity
-- Disk usage
-- Stale PID files
-- Event log integrity
-
-### CoCo Tunnel
-
-Cross-machine bus proxy. Expose a local CoCo bus to a remote machine (or vice versa) via HTTP REST, with optional authentication and sync.
-
-```bash
-# Server mode (receiving end)
-node tunnel.js server --port 9090 --secret mytoken
-
-# Client mode (sending end — pushes local agents & messages)
-node tunnel.js client --host 192.168.1.100 --port 9090 --secret mytoken
-
-# Bidirectional sync (merge agents both ways)
-node tunnel.js sync --remote http://192.168.1.100:9090 --interval 5000
-
-# SSH tunnel helper — prints port-forwarding instructions
-node tunnel.js ssh --remote user@server.example.com
-
-# Via CLI
-node coco-cli.js tunnel server --port 9090 --secret mytoken
-```
-
-**Endpoints (server):**
+- **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.
 
-| Method | Path | Description |
-|--------|------|-------------|
-| GET | `/health` | Server status + agent count |
-| GET | `/bus/agents` | List bus agents |
-| GET | `/bus/file/:path` | Read a bus file |
-| POST | `/bus/send` | Send message to bus |
-| POST | `/bus/write` | Write a bus file |
-| POST | `/bus/register` | Register an agent remotely |
-
-### Backup & Restore
-
-Gzip-compressed backup of the entire `.bus/` directory with checksum verification. Supports restore, diff, auto-backup, and cleanup.
+### External Bridges
 
-```bash
-node backup.js                         # Create timestamped backup in .backups/
-node backup.js --out mybackup.coco     # Custom output path
-node backup.js --list                  # List available backups
-node backup.js --info <file>           # Show backup metadata & contents
-node backup.js --restore <file>        # Restore bus from backup (auto-creates pre-restore backup)
-node backup.js --diff <file>           # Compare backup with current bus state
-node backup.js --cleanup 30            # Remove backups older than 30 days
-node backup.js --auto                  # Backup only if changes detected
-node backup.js --watch 60              # Auto-backup every 60 minutes
-
-# Via CLI
-node coco-cli.js backup --list
-```
+The bridge module (`bridge.js`) provides a template for two-way communication between the bus and external platforms (Slack, Discord, custom).
 
 ---
 
 ## Quick Start
 
 ```bash
-# Via npm (recommended)
+# Install globally
 npm install -g bus-agent
-npx bus-agent
 
-# Or from source (local folder still 'mcp-coco'):
-git clone https://github.com/ClewCode/bus-agent.git
-cd bus-agent
-
-# MCP mode (for any MCP client)
-node index.js
+# MCP server mode (stdio — for any MCP client)
+npx bus-agent
 
-# CLI mode (for scripts / terminal agents)
-npx bus-agent          # Run as MCP server (stdio)
-# Or with global install:
-bus status             # Check bus health
-bus agents             # List registered agents
-bus send hermes "Hello"  # Send a DM
+# CLI mode
+bus status
+bus agents
+bus send hermes "Hello"
 
-# Webhook gateway (optional)
+# Webhook gateway
+bus-agent --daemon
 node webhook-gateway.js 8080
 ```
 
-### For MCP Agents
-
-Add the following to your MCP client configuration:
+### MCP Client Configuration
 
 ```json
 {
@@ -255,13 +145,8 @@ Or from a local clone:
 ### Environment Variables
 
 ```bash
-# Your agent name on the bus
-export COCO_AGENT=my-agent
-# Windows (PowerShell)
-$env:COCO_AGENT = "my-agent"
-
-# Optional: custom data directory (default: ./.bus/ in CWD)
-export BUS_DIR=/path/to/my-bus-data
+export BUS_AGENT=my-agent           # Your agent name on the bus
+export BUS_DIR=/path/to/data         # Custom data directory (default: ./.bus/ in CWD)
 ```
 
 ---
@@ -275,113 +160,174 @@ export BUS_DIR=/path/to/my-bus-data
                     └──────┬────────────────┘
                            │
 ┌──────────┐     ┌────────┴────────────────────────┐     ┌──────────┐
-│ OpenClaw │────▶│   MCP CoCo (Agent Bus)          │◀────│  Hermes  │
+│ OpenClaw │────▶│    Bus Agent (Agent Bus)        │◀────│  Hermes  │
 │  (skill) │     │                                  │     │  Agent   │
 ├──────────┤     │  .bus/agents.json               │     ├──────────┤
 │  Claude  │────▶│  .bus/messages/                 │◀────│  Cursor  │
 │  Code    │     │  .bus/channels/                  │     │          │
 ├──────────┤     │  .bus/events/                    │     ├──────────┤
-│ OpenCode │────▶│  .bus/schedule.json              │◀────│  CLI     │
-│  (clew)  │     └────────┬─────────────────────────┘     │  agents  │
-└──────────┘              │                                └──────────┘
-                           │\
+│ OpenCode │────▶│  .bus/memory/                    │◀────│  CLI     │
+│  (clew)  │     │  .bus/schedule.json              │     │  agents  │
+└──────────┘     └────────┬─────────────────────────┘     └──────────┘
                            │
-          ┌────────────────┴────────────────────┐\
-          │  Utility Layer                      │\
-          │  doctor.js — Diagnostics & Auto-Fix │\
-          │  tunnel.js — Cross-machine Proxy    │\
-          │  backup.js — Backup, Restore & Diff │\
+          ┌────────────────┴────────────────────┐
+          │  Utility Layer                      │
+          │  Doctor — Diagnostics & Auto-Fix    │
+          │  Tunnel — Cross-machine Proxy       │
+          │  Backup — Backup, Restore & Diff    │
           └─────────────────────────────────────┘
 ```
 
-All bus state is stored as plain JSON files on disk. No database or external service required.
-
-The data directory (`.bus/`) is resolved at runtime:
+**Data storage** is resolved at runtime:
 1. `$BUS_DIR` environment variable (if set)
-2. `$CWD/.bus/` (current working directory — **default**)
+2. `./.bus/` in current working directory (default)
 
-This means each user/project gets **their own isolated data**. No cross-user data sharing. The `.bus/` folder is gitignored by default.
+Each user/project gets isolated data. The `.bus/` folder is gitignored by default.
 
----
-
-## Data Layout
+### Data Layout
 
 ```
 .bus/
   agents.json              # Agent registry with profiles
   messages/
-    <agent_name>/          # Per-agent inbox (JSON message files)
-    <agent_name>_outbox/   # Sent messages archive
+    <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 format)
+    YYYY-MM-DD.jsonl       # System events log (JSONL)
   schedule.json            # Scheduled jobs
   auto-reply-rules.json    # Auto-reply rules
-  workflows.json            # Workflow definitions
+  workflows.json           # Workflow definitions
   memory/
-    <agent>/               # Per-agent memories
-      memories.jsonl       # Append-only memory log (JSONL)
+    <agent>/
+      memories.jsonl       # Append-only memory log
       index.json           # TF-IDF inverted index
-      vectors.json         # Vector embeddings (when provider configured)
+      vectors.json         # Vector embeddings (when configured)
       config.json          # Embedding provider config
+  .backups/                # Backup archives
 ```
 
 ---
 
-## Tools Reference
+## CLI Reference
+
+```bash
+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]
+```
 
-The MCP server exposes 43 tools across 9 categories:
+---
+
+## MCP Tools (43)
 
 | Category | Count | Tools |
 |----------|-------|-------|
-| Agent Registry | 7 | `agent_register`, `agent_update_profile`, `agent_get_profile`, `agent_list`, `agent_search`, `agent_heartbeat`, `agent_set_status` |
-| Messages | 5 | `message_send`, `message_broadcast`, `message_fetch`, `message_wait`, `message_delete` |
-| Channels | 5 | `channel_create`, `channel_join`, `channel_leave`, `channel_send`, `channel_history` |
-| System Events | 2 | `system_get_events`, `system_wait_for_event` |
-| Scheduler | 3 | `scheduler_add`, `scheduler_remove`, `scheduler_list` |
-| Auto-Reply | 3 | `auto_reply_add`, `auto_reply_remove`, `auto_reply_list` |
-| Workflows | 4 | `workflow_create`, `workflow_run`, `workflow_remove`, `workflow_list` |
-| Memory | 10 | `memory_store`, `memory_search`, `memory_recall`, `memory_list`, `memory_forget`, `memory_stats`, `memory_archive`, `memory_clear`, `memory_configure`, `memory_rebuild` |
-| Utilities | 4 | `coco_health`, `ask_hermes`, `hermes_send`, `hermes_channels` |
-
-## Memory Layer
+| 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`.
 
-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 deps
+## Utility Tools
 
-**Storage:** Append-only JSONL per agent in `.bus/memory/{agent}/`
+### Doctor
 
-| 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 |
+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.
 
 ```bash
-bus memory store andul "Jonus likes clean architecture" --key architecture-pref --namespace preferences
-bus memory search andul "architecture layers" --limit 5
-bus memory configure --provider ollama --endpoint http://localhost:11434 --model nomic-embed-text
-bus memory rebuild andul
-bus memory archive andul --max-age-days 7
+bus doctor [--quick] [--fix] [--report] [--watch]
 ```
 
-## Utility Tools
+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.
+
+```bash
+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.
+
+```bash
+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
+
+![benchmark](./benchmark.svg)
 
-Three standalone (also integrated into `coco-cli.js`) tools augment the bus:
+**Environment:** Node v24.12.0 · Windows Server · File-based (no database)
 
-| Tool | File | Purpose |
-|------|------|---------|
-| Doctor | `doctor.js` / `lib/doctor.js` | Diagnostics, health checks, auto-fix |
-| Tunnel | `tunnel.js` / `lib/tunnel.js` | Cross-machine bus proxy & sync |
-| Backup | `backup.js` / `lib/backup.js` | Compressed backup, restore, diff |
+| 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 |
 
-Full tool schemas are available via MCP `tools/list` or by running `node coco-cli.js help`.
+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.
 
 ---