bifrost

# Bifrost Inter-agent message broker MCP server. Provides topology-enforced messaging between Claude Code agents via a shared SQLite database. ## How it works Each agent runs its own Bifrost MCP instance, all sharing a single SQLite database (WAL mode). Messages are routed through a deny-by-default topology — agents can only communicate along explicitly allowed paths. ## Tools | Tool | Description | |------|-------------| | `bifrost_register` | Register this agent with the broker | | `bifrost_send` | Send a message (topology-enforced) | | `bifrost_poll` | Check for new messages | | `bifrost_peers` | List reachable online agents | | `bifrost_topology` | View communication rules | | `bifrost_heartbeat` | Signal agent is alive (call every 60s) | | `bifrost_thread` | Manage conversation threads (get/list/messages/close) | | `bifrost_outbox` | View sent messages and their delivery/read status | | `bifrost_history` | Search message history (sent + received) with filters | | `bifrost_admin` | Broker admin: stats, agent list, topology rules, dead letters | | `bifrost_emergency` | Bypass topology for emergencies (restricted) | | `bifrost_spawn` | Request child agent spawn (dept leads only) | ## Install One-shot via `go run` (Go 1.17+, no clone needed): ```bash claude mcp add bifrost --env BIFROST_DB=$HOME/.bifrost.db \ -- go run github.com/syvbrunnr/bifrost/cmd/bifrost@latest ``` Or install a persistent binary: ```bash go install github.com/syvbrunnr/bifrost/cmd/bifrost@latest claude mcp add bifrost --env BIFROST_DB=$HOME/.bifrost.db -- bifrost ``` Pre-built binaries for linux/darwin × amd64/arm64 are attached to each [release](https://github.com/syvbrunnr/bifrost/releases). ## Build from source ```bash make build # current platform → .tmp/{os}-{arch}/bifrost make build-all # all platforms (linux/darwin, amd64/arm64) ``` ## Run Use the platform-detecting wrapper: ```bash BIFROST_DB=./data/bifrost.db AGENT_ROLE=gateway AGENT_DEPARTMENT=communications ./bifrost.sh ``` Or run a specific binary directly: ```bash .tmp/linux-arm64/bifrost ``` Runs on stdio (MCP transport). Environment variables: | Variable | Default | Description | |----------|---------|-------------| | `BIFROST_DB` | `./data/bifrost.db` | Path to shared SQLite database | | `BIFROST_TOPOLOGY` | | Path to SQL file with topology rules (loaded on startup) | | `AGENT_ROLE` | | Auto-register role on startup | | `AGENT_DEPARTMENT` | | Auto-register department on startup | | `AGENT_MODEL` | | Model name for registration metadata | ## MCP config Add to a claude-runner agent's MCP config: ```json { "type": "stdio", "command": "/path/to/bifrost/bifrost.sh", "args": [], "env": { "BIFROST_DB": "/shared/path/bifrost.db", "BIFROST_TOPOLOGY": "/path/to/topology.sql", "AGENT_ROLE": "gateway", "AGENT_DEPARTMENT": "communications" } } ``` The `bifrost.sh` wrapper auto-selects the correct binary for the current OS and architecture. ## Topology By default, when no topology rules are configured, all agents can communicate freely (open mode). Once any topology rule is added, communication switches to deny-by-default — agents can only communicate along explicitly allowed paths. To configure topology, set `BIFROST_TOPOLOGY` to a SQL file loaded on startup. Uses `INSERT OR IGNORE` so existing rules are preserved: ```sql INSERT OR IGNORE INTO topology (from_role, to_role, direction) VALUES ('gateway@communications', 'cio@investments', 'bidirectional'); ``` Emergency bypass allows specific roles to skip topology (e.g., risk-sentinel to executor). ## Security model Bifrost has **no authentication**. The trust boundary is the SQLite file: any process that can open it can register as any `role@department` and send messages as that identity. The topology table enforces routing, not identity — it assumes each agent process registers honestly. This is the intended model for single-host, single-operator deployments where all agent processes are under the same trust zone (e.g. all your Claude Code agents on your machine). Do not expose the database file to untrusted processes, and do not use Bifrost as-is in any multi-tenant or shared setting. Other notes: - Messages are stored unencrypted in SQLite. Treat the DB file as sensitive. - The `BIFROST_TOPOLOGY` SQL file is `Exec`'d verbatim — only load files you control. - Sender-supplied `metadata` is forwarded into channel notifications, but broker-controlled fields (`from`, `message_id`, `type`, `subject`, `thread_id`, `priority`) cannot be overridden by it. ## Test ```bash make test ``` Tests cover open topology, topology enforcement, message routing, metadata forwarding, thread management, gateway relay flow, message history search, dead letter inspection, thread auto-expiry, rate limiting, outbox tracking, and concurrent database access.