The Problem

Teams that mix human contributors with AI agents need a single, auditable event log that treats people and bots alike. Existing tools either silo AI actions behind separate APIs or expose a fragmented permission model, forcing duplicate tooling and manual sync.

What This Does

buzz delivers a self‑hostable, Nostr‑based relay that stores every message, reaction, workflow step, and git event as a signed entry. The workspace is defined by a URL, and the same log backs both human UI (React + Tailwind in admin-web/) and agent back‑ends (Rust crates under crates/).

Key components:

  • Relay core – crates/buzz-acp/src/relay.rs (176 functions) parses, validates, and routes events, also performing outbound network calls and DB writes.
  • Database layer – crates/buzz-db/src/lib.rs (262 functions) provides the persistent store used by the relay and admin services.
  • Agent interface – crates/buzz-agent/src/llm.rs (146 functions) talks to LLM providers, makes HTTP calls, and returns structured completions.
  • Admin UI – admin-web/src/App.tsx renders channels, patches, and media, driven by the same event stream the agents consume.

The repo is a portfolio of ten projects (desktop, mobile, web, admin‑web, various Rust crates, benchmarks, scripts, etc.) that share a common event‑log model while each can be built and deployed independently.

How It Is Wired

Execution starts in the Rust binary crates/buzz-acp/src/main.rs (fn main). It reaches 308 internal functions and spawns the core event loop. The most‑used internal utilities are Err (440 call sites), path (310), map (291) and bind (265), indicating that error handling and data transformation dominate the code base.

A typical request flow:

  1. Entry – main → spawn (creates a subprocess, sets BUZZ_AGENT_PROVIDER=openai).
  2. Dispatch – dispatch (in crates/buzz-agent/src/lib.rs:211) calls as_deref 99 times and eventually invokes cmd_ls, which runs a DB query via client.query.
  3. Database write – reconcile_channels (in crates/buzz-admin/src/main.rs:461) calls replace_addressable_event, which rolls back a transaction (tx.rollback).

The relay (crates/buzz-acp/src/relay.rs) is the hub for outbound network traffic and DB interaction; any change here ripples through >30 other files. The LLM module (crates/buzz-agent/src/llm.rs) is the second biggest outward‑facing component, invoking external APIs and summarising responses.

Because the call graph is resolved only for intra‑repo edges, framework callbacks (React event handlers, Kubernetes probes) are not represented, but the static analysis shows 6000 internal call edges, giving confidence that most runtime paths are traceable.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/buzz.git
cd buzz

# Install JS dependencies (pnpm is declared)
pnpm install      # pulls admin-web packages

# Build Rust crates
cargo build --workspace

# Run the relay locally (example)
cargo run -p buzz-acp   # entry point: crates/buzz-acp/src/main.rs

# Optionally spin a container
docker build -t buzz:local .
docker run -p 8000:8000 buzz:local

Configuration lives in .env.example; copy it to .env and supply Nostr keys and DB connection strings before starting. The admin UI can be launched with pnpm --filter admin-web dev (Vite dev server) and will connect to the locally running relay.

Real‑World Use

A product team hosts a private Buzz instance. When a new feature branch is pushed, a CI job (outside this repo) posts a signed git-push event to the relay. An agent subscribed to the #release channel reads the event, runs automated tests, and posts a review event with a signed receipt. Humans see the test results and agent comments in the same channel UI, and the entire decision trail is immutable.

Code Health & Issues

  • High – Several pinned Rust dependencies have known CVEs (e.g., tokio@1, nostr@0.44). Fix: upgrade to the patched versions and update Cargo.lock.
  • Medium – Dockerfile uses mutable base tags (rust:${RUST_VERSION}-${DEBIAN_VERSION}). Fix: pin images by digest.
  • Medium – No dependency‑vulnerability scan in CI. Fix: add dependency-review-action or osv-scanner.
  • Low – Workflow auto-tag-on-release-pr-merge.yml lacks timeout-minutes. Fix: set a reasonable timeout.

All other hygiene checks pass: tests (755 files), CI (GitHub Actions), licence (Apache 2.0), lockfiles, and no committed secrets.

The Bottom Line

buzz is a well‑structured, multi‑language workspace that unifies human and agent collaboration on a single signed event log. Its core Rust crates are solid but need urgent dependency upgrades and tighter container image pinning. Teams comfortable managing Rust builds and Docker deployments will find it a powerful foundation for AI‑augmented development; lighter teams may be deterred by the breadth of components and the need to secure the underlying dependencies.