From ff030e1af9ce5c1b1433aed8c4b3cd17ce77370f Mon Sep 17 00:00:00 2001 From: Matt Toohey Date: Sat, 14 Nov 2026 11:47:45 +1100 Subject: [PATCH] docs(readme): point desktop readers at block/buzz-app and describe where each client lives (#9493) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary Points README readers at [block/buzz-app](https://github.com/block/buzz-app) for the desktop app and describes this repo as the home of the relay and the mobile client. - Replaces the "Buzz 1.0 is at buzz-app" callout with a "Where to find things" table listing the desktop app, mobile client, and relay with their homes. - Drops the packaged desktop-build download table, the `BUZZ_RELAY_URL` launch note, and the "I work at Block" internal-build section; "I just want to try the app" now links to buzz-app. - Adds an "I want to work on the mobile app" path linking to `mobile/README.md`. - Reframes Quick start around the relay (`just relay` instead of `just dev`) and updates the common dev commands and architecture diagram so they no longer assume the desktop app lives here. Documentation-only change; no code touched. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Signed-off-by: Matt Toohey Co-authored-by: Claude Fable 5.2 --- README.md | 64 +++++++++++++++++++++++++------------------------------ 1 file changed, 29 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index de9636ece3..8eee291c7c 100644 --- a/README.md +++ b/README.md @@ -14,10 +14,6 @@ Apache 2.0

-> [!NOTE] -> **Buzz 1.0 is at [block/buzz-app](https://github.com/block/buzz-app).** This repository is Buzz 0.X, which is still available and supported. -> Buzz 1.0 adds [plugins](https://github.com/block/buzz-app/blob/main/docs/plugin-architecture.md); their API is a preview, so updates can break them. -

A Buzz project channel where people and an agent coordinate on a release plan

@@ -56,6 +52,18 @@ Yes, it's another AI-adjacent developer tool. We're sorry. The difference is wha --- +## Where to find things + +Buzz's open-source code lives in two repositories. The desktop app has its own; the relay and the mobile client are here. + +| Component | Home | +|---|---| +| Desktop app | [block/buzz-app](https://github.com/block/buzz-app) | +| Mobile client (iOS + Android) | This repo, in [`mobile/`](mobile/) | +| Relay | This repo, in [`crates/buzz-relay/`](crates/buzz-relay/) | + +--- + ## A look inside @@ -104,7 +112,7 @@ Agents are part of the room, not haunted cron jobs. | ✅ 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 | +| Desktop app (in [block/buzz-app](https://github.com/block/buzz-app)) | 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) | | | @@ -120,21 +128,9 @@ New to Buzz? Pick the path that matches you. ### I just want to try the app -Grab a packaged build from the [latest release](https://github.com/block/buzz/releases/latest): +The desktop app lives in [block/buzz-app](https://github.com/block/buzz-app). Head there to install, build, or run it. -| Platform | File | -|---|---| -| macOS (Apple Silicon) | `Buzz__aarch64.dmg` | -| macOS (Intel) | `Buzz__x64.dmg` | -| Linux (x86_64) | `Buzz__amd64.AppImage` or `Buzz__amd64.deb` | -| Windows (x64) | `Buzz__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. +Need a relay for it to connect to? Deploy a hosted one, or follow **Quick start** below to stand one up locally. ### I want my own hosted relay @@ -144,20 +140,20 @@ To run a relay for your team without managing servers, you can deploy one to Rai See [here](https://engineering.block.xyz/blog/run-your-own-buzz-relay) 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](https://github.com/squareup/buzz-releases/releases/latest) and install it. - -### I want to build & run from source +### I want to run the relay from source See **Quick start** below — this is the developer / self-host path. +### I want to work on the mobile app + +The Flutter client is in [`mobile/`](mobile/). See [mobile/README.md](mobile/README.md) for setup and run instructions. + --- ## Quick start +This stands up the relay locally. For the desktop app, see [block/buzz-app](https://github.com/block/buzz-app); for the mobile app, see [mobile/README.md](mobile/README.md). + You'll need [Docker](https://docs.docker.com/get-docker/) and [Hermit](https://cashapp.github.io/hermit/) (or Rust 1.88+, Node 24+, pnpm 10+, `just`). **Once:** @@ -172,12 +168,10 @@ just setup && just build **Every day:** ```bash . ./bin/activate-hermit -just dev # starts the relay + desktop app together +just relay # starts the relay (and its Docker services if needed) ``` -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. +Relay on `ws://localhost:3000`. You're in. Want a single-node / VPS relay instead of the local-dev stack? Use the production Compose bundle in [`deploy/compose/`](deploy/compose/README.md) (`docker compose` + Postgres, Redis, MinIO, optional Caddy/TLS). The root [`docker-compose.yml`](docker-compose.yml) is for day-to-day development only. @@ -201,7 +195,7 @@ If you'd rather point buzz at a different bash-compatible shell, set `BUZZ_SHELL ┌─────────────────────────────────────────────────────────────────────────┐ │ Clients │ │ Human client AI agent CLI / scripts │ -│ (Buzz desktop) (Goose, Codex, ...) (buzz-cli, agents) │ +│ (desktop, mobile) (Goose, Codex, ...) (buzz-cli, agents) │ │ │ ┌──────────────┐ │ │ │ │ │ buzz-acp │ │ │ │ │ │ (ACP ↔ MCP) │ │ │ @@ -222,7 +216,7 @@ If you'd rather point buzz at a different bash-compatible shell, set `BUZZ_SHELL └──────────────┘ ``` -A Rust workspace of focused crates. Single source of truth: the relay. See [ARCHITECTURE.md](ARCHITECTURE.md) for the full breakdown. +A Rust workspace of focused crates. Single source of truth: the relay. The human clients are the desktop app in [block/buzz-app](https://github.com/block/buzz-app) and the mobile app in [`mobile/`](mobile/). See [ARCHITECTURE.md](ARCHITECTURE.md) for the full breakdown.
Crate map @@ -261,11 +255,11 @@ All defaults work out of the box. Override via `.env`. Full reference in [`.env. Common dev commands ```bash -just setup # Docker, migrations, desktop deps +just setup # Docker, migrations, JS deps just relay # Run the relay -just dev # Run the desktop app +just mobile-dev # Run the mobile app in an iOS Simulator just build # Build the Rust workspace -just check # fmt + clippy + desktop check +just check # Lint, formatting, and repo policy checks just test-unit # Unit tests (no infra required) just test # Full suite (starts services if needed) just ci # Everything CI runs