e94b547f60
## Summary The timeline freezes its live tail when Virtua reports that the reader has left the bottom, and a send arms a one-shot pin for its own row. A not-at-bottom report between the send and the sent row reaching the deferred snapshot froze the tail again, so the sent row waited behind a "1 new message" pill. That is the `messaging.spec.ts:483` flake in Desktop Smoke E2E. The first commit holds off that freeze while the send is pending. The other three are follow-ups from pre-PR review that bound the hold to the send itself: it ends when the row lands, it is disarmed when the send fails, and it is armed only for the channel the send belongs to. ### fix(desktop): keep an own send out of the frozen timeline tail #### Problem `messaging.spec.ts:483` "long autolink wraps without widening the timeline" flaked in Desktop Smoke E2E at :497: the timeline never showed the sent message. The composer was empty, and a "1 new message" pill sat at the bottom of a timeline that was already at the floor. - seiler/BUZZ-517/desktop-upgrade-guidance: - https://github.com/block/buzz/actions/runs/41751914119/job/126319694104 (retry 1 passed) The failure video shows the composer filling while the channel still showed its skeleton, the rows rendering under the tall composer, and the send landing about 120 ms later. #### Cause The timeline freezes its live tail when Virtua reports that the reader has left the bottom, and later rows wait behind the pill. A send lifts the freeze and arms a one-shot pin for the next append (`prepareForOwnMessage`). Nothing kept a not-at-bottom report between the send and the sent row reaching the deferred snapshot from freezing the tail again. The sent row then waited behind the pill, and the pin, which waits for that append, never fired. Only a later scroll to the floor would have released it. Virtua 0.49.3 makes that report while the reader sits at the floor. It applies a list length change to its store during render (Virtualizer.tsx). React discarded the deferred render that added the sent row, but the store kept the row's estimated height. When the cleared composer shrank the trailing spacer, the next scroll event put the reader 96 px from a floor the DOM didn't have: Virtua read 941 - 479 - 366 = 96, the DOM read 917 - 551 - 366 = 0. The freeze it queued renders at default priority, ahead of the deferred render, which then restarted against the frozen tail. #### Fix While the send's pin is armed, a not-at-bottom report doesn't freeze the tail. `useAnchoredScroll` exposes `isBottomPinArmed()`, which reads the pin's own flag, so the hold ends when the pin fires or the channel changes. `prepareForOwnMessage` also cancels a freeze queued before the send, which would otherwise land after its release. Bottom state still comes from Virtua. Reading it from the DOM would add false gaps of its own, because unmeasured rows overflow their slots: a passing run read 51 px from the DOM where Virtua read 0. A scroll up between the send and its row no longer freezes the tail. The pin brings the reader down to the sent row, as it already does when the row lands first. A send that adds no row leaves the pin armed until the next append, as before, and the hold follows it. #### Validation - New `MessageTimeline.ownSend.jsdom-test.mjs` renders the real MessageTimeline over Virtua with a modelled layout and manual frames. It sends with a gap reported after the send, and with a freeze already queued at the send. The sent row must render at the floor with no pill. Without the pin guard the first case fails, and without the cancel the second does, each showing "1 new message". - Repro, using temporary, uncommitted changes: the test with a 600 ms channel-head delay, filling during the skeleton, sending once rows render, with CPU throttled 4x over CDP. Without the fix: 3/20 failed with the CI signature, and instrumentation showed the 96 px report above. With the fix: 40/40 passed, and 6 of those runs logged a not-at-bottom report while the pin was armed. - `messaging.spec.ts --grep "long autolink"`: 30/30 passed at 4 workers, 10/10 serially. - messaging, virtualization, scroll-history, stream, smoke, thread-follow, file-attachment and message-target-highlight specs, run twice at 4 workers: 185 passed and 1 failed each time, a different test each run. Repeating those two fails as often without the fix: `:2785` (own avatar) 22/25 vs 20/25 at 4 workers and 8/10 vs 9/10 serially; `:3170` (thread panel width) 4/25 vs 8/25 and 1/10 vs 3/10. `:2785` fails on the avatar image after its message has rendered, and `:3170` never sends, so the change can't reach it. - `tsc --noEmit`, `biome check`, and the messages UI unit (337) and jsdom (9) tests pass. A green run doesn't prove the flake is gone. Hosted CI covers broad validation. ### fix(desktop): end an own send's freeze hold when its row lands #### Problem Review off2c57afb5("fix(desktop): keep an own send out of the frozen timeline tail") raised two findings in MessageTimeline.tsx. - Warning: the hold on freezing the tail lasted as long as the send's bottom pin, not as long as the send. The pin fires only when the tail id changes (`newLatestArrived` in useAnchoredScroll), and only firing or a channel change cleared it. The window cache sorts rows by created_at, so the sent row doesn't become the tail when the last row has a later created_at (a sender whose clock runs ahead) or a same-second row sorts after it. The pin then stayed armed after the sent row rendered, and a reader who scrolled up never froze the tail. The next arrival to become the tail fired the pin and pulled them to the bottom instead of showing the pill. Beforef2c57afb5the freeze buffered that arrival, so a stale pin could not fire under a reader. - Nit: `prepareForOwnMessage` set `semanticAtBottomRef.current = true`, which the hold already made redundant, and cancelling the queued freeze left behind the `suppressNextSemanticBottomRef` it had set. #### Cause The hold read the bottom pin's own flag. The pin is cleared only when it fires on a new tail id (`newLatestArrived` in useAnchoredScroll) or when the channel changes. The window cache sorts rows by `created_at`, so a sent row that sorts above the current tail never becomes the tail. That happens when the last row's sender has a clock running ahead, or when a same-second row sorts after the sent one. The pin then stays armed after the sent row renders, and the hold stays with it. #### Fix `useAnchoredScroll` keeps a pending-send flag next to the pin. `scrollToBottomOnNextUpdate` sets both. The restoration effect clears the flag on the first append after arming, whether or not it moves the tail (`newLatestArrived` or an "append" delta), and the channel reset clears it. `isBottomPinArmed` becomes `isOwnSendPending`, which reads the flag, and MessageTimeline holds off freezing only while it is set. The pin itself is unchanged and still waits for a new tail. Once the hold ends, a reader who scrolls up freezes the tail as before, so later arrivals wait behind the pill and a stale pin can't fire under them. This keeps arming and disarming in the hook. Disarming from ChannelPane after `onSendMessage` settles would need a second call site (the welcome add-agent flow also arms the pin), and the send's promise isn't tied to when the sent row reaches the deferred snapshot. `prepareForOwnMessage` now clears `suppressNextSemanticBottomRef` instead of setting the semantic ref, so dropping the queued freeze also drops the suppression it armed. No test covers this: a leftover suppression only swallowed a bottom report while the send's release was already making the timeline semantically at the bottom. #### Validation - New case in `MessageTimeline.ownSend.jsdom-test.mjs`: the tail's createdAt is an hour ahead, the send lands above it, the reader scrolls up 200 px, and a row from the same fast clock arrives and becomes the tail. It expects "1 new message" and the reader's offset unchanged. Onf2c57afb5it fails: no pill, and the pin moved the reader from 756 to the floor at 1052 and rendered the arrival. With the fix the reader stays at 756 and the arrival waits behind the pill. - Mutations: clearing the flag only on a new tail, or never on an append, fails only the new case. Removing the hold check fails the original "gap after the send" case, as before. - Messages UI jsdom tests (10) and `src/features/messages` unit tests (1530) pass. Full desktop `pnpm test`: 6933 unit and 179 jsdom tests pass. - `tsc --noEmit`, `biome check` on the changed files, `check:file-sizes` and `git diff --check` are clean. No browser E2E was run for this follow-up. ### fix(desktop): disarm an own send's pin and hold when the send fails #### Problem Second review of the branch (warning, regression vs main) onc1767345e("fix(desktop): end an own send's freeze hold when its row lands"), useAnchoredScroll.ts and ChannelPane.tsx. The hold can still go stale when a send never adds a row to this timeline. `ChannelPane.handleSendMessage` armed the pin and the hold before it awaited `onSendMessage`, for every main-composer send. That includes a DM send that `useMentionSendFlow`'s `onPrepareSendChannel` moves to another DM (the message mentions an agent who isn't in this one). Its optimistic row goes to that channel's window, and `goChannel` runs only after the send succeeds. If the publish is rejected or times out, the user stays on the original DM with both flags armed. A same-channel send whose `onMutate` can't resolve the channel also adds no row. Then the reader scrolls up, the hold skips the freeze, the next arrival from the other person becomes the tail, and the stale pin moves the reader to the bottom with no pill. The reviewer's jsdom repro: at HEAD, no pill and scrollTop 660 -> 956. At the merge base, "1 new message" and 660 stays. A failed send to the same channel was fine: its optimistic row lands in `onMutate`, an append that clears the hold, and is then reverted. #### Cause `ChannelPane.handleSendMessage` armed the pin and the hold before it awaited `onSendMessage`, for every main-composer send, and nothing disarmed them if the send then added no row to this timeline. A send that `onPrepareSendChannel` moves to another DM lands its optimistic row in that channel's window. A same-channel send whose `onMutate` can't resolve the channel adds no row either. When such a send fails, the user stays on the original timeline with both flags still armed. #### Fix - `ChannelPane.handleSendMessage` arms only when the send targets this channel (`!channelId || channelId === activeChannelId`). A send prepared into another channel lands its row there, and the pane navigates to it once the send succeeds. - `MessageTimelineHandle.cancelScrollToBottomOnNextUpdate` disarms a send. `useAnchoredScroll` clears the pin and the pending-send flag. The hold skipped every freeze while the send was pending, including one queued before the send that the arm cancelled. So if the send was still pending and Virtua's last report has the reader off the floor, the cancel queues that freeze, as the report would have without the hold. Later arrivals then wait behind the pill. If the send's row already landed, the hold had ended and the cancel only clears the pin. - `ChannelPane` arms through `armOwnSend`, which returns the disarm. The main composer calls it when `onSendMessage` rejects, and the Welcome "create in chat" flow when its `mutateAsync` rejects. Its `beforeSend` option now returns the disarm. A generation counter keeps a late failure from disarming a pin that a later send armed. #### Validation - `MessageTimeline.ownSend.jsdom-test.mjs` adds the reviewer's no-row case in three orders: fail before the reader scrolls up, after, and with the freeze queued before the send. Each expects "1 new message" and the reader's offset unchanged after a new tail arrives. With the cancel a no-op (HEAD's behavior), all three fail: no pill, and the reader moves from 660 to 956. With the cancel clearing the flags but not queueing the freeze, the two orders where the reader left the floor during the send fail with "Jump to latest". A fourth case, a same-channel send whose row lands and is then reverted, still shows "1 new message" and keeps the offset. It passes on HEAD as well, because it pins behavior that must not change. 7/7 pass. - `useAnchoredScroll.lifecycle.test.mjs` adds a hook case: arm, cancel, the reader leaves the floor, a new tail arrives without a jump, and a later send still pins. It fails if the cancel is a no-op, or if it clears only the pending flag. useAnchoredScroll unit tests: 45/45. - Full desktop `pnpm test`: 6934 unit and 183 jsdom tests pass. - `tsc --noEmit`, `biome check --error-on-warnings` on the changed files and `git diff --check` are clean. - No test renders `ChannelPane`, so its arm condition, the rejection handlers and the generation counter are covered only by tsc and review. No browser E2E was run. ### fix(desktop): arm an own send's pin only for the channel it belongs to #### Problem Third review of the branch (review 89cce157, warning) onc257ff169("fix(desktop): disarm an own send's pin and hold when the send fails"), ChannelPane.tsx. `handleSendMessage` armed the timeline when `!channelId || channelId === activeChannelId`, and `activeChannelId` was the value captured in its closure. A send whose slow upload spans a channel switch passes that check against the channel it was written in, then arms `messageTimelineRef.current`, the timeline now showing the other channel. That channel keeps its tail open and its pin armed until its next append, because the sent row lands in the original channel's window. A reader who scrolls up there doesn't freeze the tail, and the next arrival fires the pin and pulls them to the bottom with no pill. #### Cause `useMentionSendFlow` reads `onSendRef.current` before it starts a deferred upload and calls that `send` from the upload's `onComplete`. The arm carried no channel, so only the stale closure decided whether to arm, and the timeline accepted an arm for whatever channel it rendered. #### Fix - `MessageTimelineHandle.scrollToBottomOnNextUpdate(sendChannelId)` takes the send's channel. `useAnchoredScroll` keeps the channel its state belongs to in a ref that its channel reset updates, and its arm returns false without arming for any other channel. MessageTimeline releases the frozen tail only when the arm is accepted, so a stale send neither releases nor pins the channel shown now. - The arm and disarm move from ChannelPane into `useOwnSendArm(timelineRef, getTimelineChannelId)`. It skips an arm whose channel isn't the one `getTimelineChannelId` reads now (ChannelPane passes its `activeChannelIdRef`) and returns a no-op disarm. A skipped arm leaves the generation alone, so it can't stop a pending send in the shown channel from disarming when it fails. Otherwise the generation works as before: a later send's arm turns an earlier send's disarm into a no-op. - `handleSendMessage` arms `channelId ?? activeChannelId`. A send prepared into another DM is still skipped, now by the hook's live check instead of the closure. - The Welcome "create in chat" flow names the channel it sends to: `beforeSend` takes a `channelId`, and `useWelcomeAgentCreate` passes `activeChannel.id`. - `useAnchoredScroll` exposes `isVirtualizerAtBottom()`, and MessageTimeline's cancel reads it instead of keeping its own copy of Virtua's last report. The two agree once the channel has confirmed its bottom, which the cancel already requires. The hook's copy is also cleared by a target jump or a live row under a held target before Virtua reports, so a cancel in that window freezes as the report would. - The channel reset effect now reads `channelId`, so its exhaustive-deps suppression goes. "a cancelled own send leaves the next tail with the reader" in `useAnchoredScroll.lifecycle.test.mjs` (fromc257ff169) failed 3 of 6 runs at HEAD on this workstation. The mount's settling frame, a `setTimeout(0)` in that file's shim, could run after the test cleared its recorded pins and add a "jump". The test now waits for that frame first, as other cases in the file do: 0 of 15 runs failed. It still fails when the cancel is a no-op or clears only the pending flag. #### Validation - New `useOwnSendArm.test.mjs` (node:test, like the rest of desktop's unit tests): a send to the shown channel arms it, a send that settles after a switch isn't armed and leaves the pending send's disarm working, a failed send disarms, and a later arm outlives an earlier failure. Each mutation fails a case: dropping the live check, bumping the generation before it, dropping the generation check, and a no-op disarm. - `useAnchoredScroll.lifecycle.test.mjs` adds an 11-row table for the two gates the cancel reads, `isOwnSendPending()` and `isVirtualizerAtBottom()`: no send, a send whose row hasn't landed, landed as the tail, landed above the tail, a send to another channel, a send then a channel change, a channel change then a send there, and the reader off the floor, back at it, after a channel change, and with a send pending. Dropping the arm's channel check, not updating the channel ref on reset, and a constant `isVirtualizerAtBottom` each fail rows. - `MessageTimeline.ownSend.jsdom-test.mjs`, 9/9: - New: with the reader scrolled up and an arrival behind the pill, an arm for another channel and a second arrival leave "2 new messages" and the offset unchanged. It fails if useAnchoredScroll accepts the arm, or if MessageTimeline releases the tail when it is refused. - New: a send that fails at the floor leaves the next arrival rendered at once. Without the off-floor gate the cancel freezes and the arrival is missing right after it renders. - Extended: after a same-channel send lands and fails, the reader returns to the floor and the arrival renders with the pill gone. Without the pending gate the cancel re-arms the freeze's bottom-report suppression and the arrival stays behind the pill. - The existing cases now pass the channel. - Desktop unit tests under `src/features/messages` and `src/features/channels`: 2006/2006. jsdom tests there: 21/21. - Playwright smoke after `pnpm build:e2e`, `--workers=4`: messaging, send-channel-binding and welcome-agent-modal-screenshots, run twice. First run 99 passed and 1 failed, second run 98 passed and 2 failed: - `messaging.spec.ts:2785` (own avatar) fails on the avatar image after its message renders: 5/6 failed with this change and 6/6 at HEAD (`--workers=2 --repeat-each=6`).f2c57afb5recorded the same local failure. - `messaging.spec.ts:3170` (thread panel width) never sends. It passed 5/5 on rerun. - `send-channel-binding.spec.ts`, `--repeat-each=5`: 10/10. Its mid-send case switches channels while a send is in flight. welcome-agent-modal-screenshots (its chat-first case clicks "create in chat" and finds the message in the timeline) plus nine messaging cases including "long autolink" and the channel-switch cases, `--repeat-each=5`: 80/80. - `tsc --noEmit`, `biome check --error-on-warnings` on the changed files, `check:file-sizes` and `git diff --check` are clean. - No test renders ChannelPane, so its getter and its `armOwnSend(channelId ?? activeChannelId)` call are covered only by tsc, the hook's tests and the specs above. **Rebased onto origin/main `64d12e297` (this branch, all four commits):** Linux workstation. This branch doesn't include the Virtua patch change from #9094. `pnpm install --frozen-lockfile` installs main's virtua patch (`30a7a92b9480...`), so every result below runs against the Virtua build on main. - `pnpm typecheck` and `biome check --error-on-warnings` on the 11 changed desktop files are clean. - Unit tests under `src/features/messages` and `src/features/channels`: 2006/2006. jsdom tests there: 16/16, including all 9 `MessageTimeline.ownSend.jsdom-test.mjs` cases. Full desktop `pnpm test`: 6949 unit and 180 jsdom tests passed. - Playwright smoke after `pnpm build:e2e`, `--workers=4 --retries=0`: messaging, send-channel-binding, scroll-history, virtualization, timeline-no-shift, overscroll-boundary, live-broadcast-reply-timeline, message-target-highlight and welcome-agent-modal-screenshots, 142 passed and 2 failed. The failures are `messaging.spec.ts:2785` (own-message avatar), which fails the same way on main here as noted above, and `messaging.spec.ts:3170` (thread panel width), which never sends and passed 5/5 on rerun. - `messaging.spec.ts --grep "long autolink"`, `--repeat-each=30`: 30/30 passed. `send-channel-binding.spec.ts`, `--repeat-each=5`: 10/10 passed. ## Coordination - #6695 ("feat: show thread replies in channel") gains a textual conflict in `desktop/src/features/channels/ui/ChannelPane.tsx`. It already conflicts with main in four other files, so it needs a rebase anyway. - #8563, #8565, #8030, #7604, #7657, #7499, #5563 and #4663 touch `MessageTimeline.tsx`, `ChannelScreen.tsx`, `ChannelPane.tsx` or `useChannelIntro.tsx` and merge cleanly with this branch. - Older open PRs that touch these files already conflict with main, and none gains a new conflict from this branch. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Signed-off-by: mtoohey <mtoohey@squareup.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Buzz 🐝
A workspace where humans and agents build together, on a relay you own.
Vision · Sovereign · Forge · Agents · Architecture · Releasing · Apache 2.0
People and agents building together in the same room.
What is this, really?
Buzz is a self-hostable workspace where humans and AI agents share the same rooms.
A Buzz community is the workspace a user reaches by URL. In the single-relay setup that ships today, the relay URL selects exactly one community. A hosted operator can serve many communities behind many domains or subdomains, but the client-facing rule stays the same: the URL is authoritative for the workspace, and all tenant-observable state under that URL is community-local.
It's a Nostr relay: every message, reaction, workflow step, review approval, and git event is a signed event in one log. Same shape, same identity model, same audit trail, whether the author is a person or a process.
In practice it feels like a team workspace. Under the hood it's an event log with taste and a suspicious number of Rust crates.
Yes, it's another AI-adjacent developer tool. We're sorry. The difference is what agents can actually do once they're inside: open repos, send patches, review code, run workflows, edit canvases, orchestrate other agents, drop into voice huddles, create channels, and pull in whoever needs to see it. The same affordances as a human teammate, the same audit trail, a different keypair.
Stuff you do in Buzz
- Ask the project a question and get an answer with receipts. Agents search six months of history and post the threads, not vibes.
- Let an agent triage a bug without giving it the keys to the kingdom. Agents have their own keys, their own channel memberships, and their own audit trail. Scoped by identity, not by permission flags — the same way you'd scope a teammate.
- Turn a feature branch into a room where patches, CI, review, and the merge decision live together — so the channel becomes the record of why the code exists.
- Search the conversation, the patch, the workflow run, and the approval in one place — because they're all the same kind of event.
- Let an agent run the workspace, not just talk in it. Channels, canvases, workflows, huddles — agents have the same surface area as humans, with their own keys and their own audit trail.
A look inside
 Agents are members, not bots. Add an agent to a channel the same way you add a person. |
 Spin up a room in seconds. Name it, describe it, make it private. |
 Media you can talk about. Leave comments pinned to specific frames. |
|
Why Buzz is better
One community. One identity model. One event log. Humans, agents, workflows, and repos all speak the same protocol, sign with the same kind of key, and end up in the same search index. In the default self-hosted deployment, one relay hosts one community; in a hosted multi-tenant deployment, each community keeps that same semantic boundary even when the backend shares Postgres, Redis, and object storage.
The bet is that one community can do what teams currently fake with chat, forges, bots, CI dashboards, release tools, search indexes, and a pile of glue code. Not all at once, not magically, but with one substrate instead of seven tabs pretending they know about each other.
Agents are part of the room, not haunted cron jobs.
Three little stories
Incident memory. It's 2am. You type "have we seen this error before?" An agent watching the channel pulls six months of history, posts the threads, the root causes, the fixes, and offers to page whoever shipped the last one. The whole exchange — question, answer, evidence — stays in the channel.
Branch as room. You open a feature branch. A channel appears. Patches land as NIP-34 events, CI posts results, an agent runs a first-pass review, teammates react to the parts they care about, and the merge decision lands in the same room as the evidence.
A release that writes itself. A workflow fires on a tag. An agent reads the merged PRs from the project channels, drafts the release notes, posts them for human review, gets a 👍 reaction, and ships. Every step signed. Every step searchable.
Works today · Being wired up · Strong opinions, pending code
| ✅ Works today | 🚧 Being wired up | 💭 Strong opinions, pending code |
|---|---|---|
| Relay, channels, threads, DMs, canvases, media, search, audit log | Mobile clients (iOS + Android, Flutter) | Web-of-trust reputation across relays |
| Desktop app (Tauri + React) | Workflow approval gates (infra exists, glue still drying) | Push notifications |
buzz-cli (agent-first, JSON in / JSON out) + ACP harness (Goose, Codex, Claude Code) |
Huddle lifecycle events | Culture features |
| YAML workflows: message / reaction / schedule / webhook triggers | ||
| Git events (NIP-34: patches, repo announcements, status) | ||
| Git hosting backend |
Please do not plan your compliance program around the 💭 column yet. The VISION docs are the long version of what we think this becomes.
Getting started
New to Buzz? Pick the path that matches you.
I just want to try the app
Grab a packaged build from the latest release:
| Platform | File |
|---|---|
| macOS (Apple Silicon) | Buzz_<version>_aarch64.dmg |
| macOS (Intel) | Buzz_<version>_x64.dmg |
| Linux (x86_64) | Buzz_<version>_amd64.AppImage or Buzz_<version>_amd64.deb |
| Windows (x64) | Buzz_<version>_x64-setup_alpha-unsigned.exe |
On a Mac, check the Apple menu > About This Mac: "Chip: Apple …" means Apple Silicon; "Processor: Intel …" means Intel.
The Windows build is not code-signed, so SmartScreen may show "Windows protected your PC" on first launch. If available, click More info, then Run anyway.
By default the app connects to ws://localhost:3000. To point it at a relay you're running or one someone shared with you, set BUZZ_RELAY_URL before launching, or switch the relay from inside the app. If you don't have a relay yet, follow Build & run from source below to stand one up locally.
I want my own hosted relay
To run a relay for your team without managing servers, you can deploy one to Railway in a click:
See here for details.
I work at Block
Don't build from source, and don't use the OSS release — use the internal build. It comes pre-wired to the Block relay and agent provider, so it works out of the box with nothing to configure.
Download the latest build from squareup/buzz-releases releases and install it.
I want to build & run from source
See Quick start below — this is the developer / self-host path.
Quick start
You'll need Docker and Hermit (or Rust 1.88+, Node 24+, pnpm 10+, just).
Once:
git clone https://github.com/block/buzz.git && cd buzz
. ./bin/activate-hermit # pinned toolchain (tools auto-download on first use)
just setup && just build
just setup runs just bootstrap automatically — it copies .env.example to .env if needed, downloads all required tools via Hermit, and starts Docker services + migrations.
Every day:
. ./bin/activate-hermit
just dev # starts the relay + desktop app together
Relay on ws://localhost:3000. Desktop app pops up. You're in.
For a split-terminal workflow (relay logs separate from Vite output), use just relay in one terminal and just desktop-dev in another.
Want a single-node / VPS relay instead of the local-dev stack? Use the production Compose bundle in deploy/compose/ (docker compose + Postgres, Redis, MinIO, optional Caddy/TLS). The root docker-compose.yml is for day-to-day development only.
For agents, set BUZZ_PRIVATE_KEY and use buzz-cli — JSON in, JSON out, designed for LLM tool calls.
Windows prerequisites
The agent shell tool runs commands under bash. On macOS and Linux that's already there; on Windows you need to bring it.
Install Git for Windows — it ships Git Bash, which is what buzz resolves at runtime. Once it's installed, everything works the same as on other platforms.
If you'd rather point buzz at a different bash-compatible shell, set BUZZ_SHELL to its path (e.g. BUZZ_SHELL=C:\path\to\bash.exe). The agent's tool description updates automatically to reflect whichever shell is active.
Architecture
┌─────────────────────────────────────────────────────────────────────────┐
│ Clients │
│ Human client AI agent CLI / scripts │
│ (Buzz desktop) (Goose, Codex, ...) (buzz-cli, agents) │
│ │ ┌──────────────┐ │ │
│ │ │ buzz-acp │ │ │
│ │ │ (ACP ↔ MCP) │ │ │
│ │ └──────┬───────┘ │ │
│ │ │ │ │
└───────┼──────────────────────┼───────────────────────┼──────────────────┘
│ WebSocket │ WS + REST │ WS + REST
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ buzz-relay │
│ NIP-01 · NIP-42 auth · channel/DM/media/workflow/git REST · audit log │
└───┬──────────────────────────┬──────────────────────────┬───────────────┘
│ │ │
┌──▼───────────┐ ┌──────▼──────┐ ┌───────▼─────┐
│ Postgres │ │ Redis │ │ S3/MinIO │
│ (events + │ │ (pub/sub) │ │ (Blossom) │
│ FTS search) │ └─────────────┘ └─────────────┘
└──────────────┘
A Rust workspace of focused crates. Single source of truth: the relay. See ARCHITECTURE.md for the full breakdown.
Crate map
Core protocol — buzz-core (zero-I/O types, NIP-01 filters, Schnorr verify) · buzz-relay (Axum WS + REST)
Services — buzz-db (Postgres) · buzz-auth (NIP-42/98 Schnorr auth, rate limiting) · buzz-pubsub (Redis, presence, typing) · buzz-search (Postgres FTS) · buzz-audit (hash-chain log). Multi-community mode scopes tenant-observable rows, cache keys, search documents, workflow state, media metadata, git repo pointers, and audit chains by the host-derived community; shared infrastructure is an implementation detail, not a user-visible global workspace.
Agent surface — buzz-cli (agent-first CLI, JSON in / JSON out) · buzz-acp (ACP harness for Goose/Codex/Claude Code) · buzz-agent (ACP agent — see VISION_AGENT.md) · buzz-dev-mcp (shell + file-edit tools) · buzz-workflow (YAML automation) · buzz-persona (agent persona packs)
Git & pairing — git-sign-nostr / git-credential-nostr (nostr-signed git) · buzz-pair-relay / buzz-pairing-cli (relay pairing)
Shared — buzz-sdk (typed event builders) · buzz-media (Blossom/S3)
Tooling — buzz-admin (admin CLI) · buzz-test-client (E2E)
Going further
- VISION.md · VISION_SOVEREIGN.md · VISION_PROJECTS.md · VISION_AGENT.md — the four vision docs
- ARCHITECTURE.md — system design, kind ranges, subsystem boundaries
- TESTING.md — multi-agent E2E test suite
- CONTRIBUTING.md · CODE_OF_CONDUCT.md · SECURITY.md · GOVERNANCE.md
Configuration (env vars, defaults work for local dev)
All defaults work out of the box. Override via .env. Full reference in .env.example.
Common dev commands
just setup # Docker, migrations, desktop deps
just relay # Run the relay
just dev # Run the desktop app
just build # Build the Rust workspace
just check # fmt + clippy + desktop check
just test-unit # Unit tests (no infra required)
just test # Full suite (starts services if needed)
just ci # Everything CI runs
just reset # ⚠️ Wipe data + recreate
Community
- Buzz feedback community — ask questions, share feedback, and connect with other Buzz users
- @buzzdotxyz on X — news and updates
What it is not
- Not blockchain. Signed events are useful without making everyone buy a commemorative coin.
- Not an AI replacement plan. Buzz works best when humans stay in the loop and agents stay in the room.
- Not finished. We will tell you what works and what doesn't.
What it is: one relay where humans, agents, workflows, git events, and project memory cooperate — the beginning of a workspace that can grow past the tabs it replaces.
Buzz 🐝
Apache 2.0 · Built by Block, Inc.