Skip to content

Commit 680dd34

Browse files
matt2eclaude
matt2e
and
claude
committed
docs(readme): show where each client and the relay live
The desktop app now lives in block/buzz-app, while the mobile client and the relay stay in this repo. The top-level README still read as the desktop app's home: it led with desktop downloads and `just dev`. What I found before writing: `desktop/` still exists here (about 3,450 tracked files, last touched 2026-11-12). Its own README and CONTRIBUTING.md call it the deprecated Buzz 0.X desktop app, kept for 0.X bug fixes. So the README does not say the code is gone. It names block/buzz-app as the desktop app's home and describes `desktop/` as leftover 0.X code. The mobile client is in `mobile/` and the relay's entry point is `crates/buzz-relay/`; both links were checked against the tree. Added - "Where to find things" at the top: a table mapping desktop app to block/buzz-app, mobile client to `mobile/`, relay to `crates/buzz-relay/`. It replaces the old note that called this whole repository "Buzz 0.X". - "I want to work on the mobile app" under Getting started, pointing at mobile/README.md. Removed (desktop-only) - "I just want to try the app": the packaged-build table, the Apple Silicon vs Intel hint, the Windows SmartScreen note, and the `BUZZ_RELAY_URL` launch instructions. A pointer to block/buzz-app takes their place. - "I work at Block": the internal desktop build download. - Quick start: `just dev`, "Desktop app pops up", and the split-terminal `just desktop-dev` workflow. - Common dev commands: `just dev`. Rewritten - The top note: it now describes `desktop/` as deprecated 0.X code that takes bug fixes only, using the wording of desktop/README.md, instead of "still available and supported". The plugin-preview sentence is kept. - "I want to build & run from source" is now "I want to run the relay from source". - Quick start says up front that it stands up the relay, and its daily command is `just relay`. The relay hint that sat in the desktop section ("if you don't have a relay yet") moved into the buzz-app pointer. - Status table: "Desktop app (Tauri + React)" now links block/buzz-app. - Architecture: the diagram's human client reads "(desktop, mobile)", and the text below names where each client lives. - Common dev commands: `just setup` and `just check` comments no longer describe them in desktop terms, and `just mobile-dev` is listed. Left as is - Prerequisites (Docker, Hermit, Rust, Node, pnpm): `just relay` runs `just bootstrap`, which still checks node and pnpm. - "Windows prerequisites": `BUZZ_SHELL` is read by buzz-dev-mcp and buzz-agent in this repo, not by the desktop app. - Product screenshots and the Releasing link. The README has no table of contents or badges, and nothing else in the repo links to the anchors that changed. Follow-ups noticed, not changed here - Justfile: `just dev`, the `desktop-*` recipes, `release-desktop`, and `check`/`ci` still build and test `desktop/`; the `setup` comment says "install desktop deps". - scripts/dev-setup.sh installs desktop dependencies and prints "just dev # start the desktop app" as a next step. - CONTRIBUTING.md: "Running the Relay and Desktop App" (`just dev`, `just desktop-dev`), the Node/pnpm rows "required for desktop app commands", the Linux desktop system libraries, and the dev desktop state notes. - RELEASING.md documents a Desktop release lane (`just release-desktop`) and never mentions block/buzz-app. The block/buzz Releases page still serves "Buzz Desktop v0.5.x" builds. - AGENTS.md: desktop E2E, PR screenshot, and "Desktop App" sections. - TESTING.md, ARCHITECTURE.md, SECURITY.md ("Desktop Secret Storage"), CONTEXT.md, VISION.md, docs/linux-rendering-troubleshooting.md, docs/admin/README.md, docs/buzz-shared-compute-dev.md, crates/buzz-acp/README.md, crates/buzz-cli/README.md, and examples/README.md mention the desktop app with no pointer to block/buzz-app. - .github/workflows: `_ci-desktop.yml`, `_ci-desktop-macos.yml`, `desktop-release-candidate.yml`, `desktop-release-cache-proof.yml`, and `promote-oss-desktop-release.yml` still build and release `desktop/`. Co-Authored-By: Claude Fable 5.2 <[email protected]> Signed-off-by: Matt Toohey <[email protected]>
1 parent 3c0adc1 commit 680dd34

1 file changed

Lines changed: 27 additions & 31 deletions

File tree

‎README.md‎

Lines changed: 27 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,18 @@
1414
<a href="LICENSE">Apache 2.0</a>
1515
</p>
1616

17+
## Where to find things
18+
19+
Buzz's open-source code lives in two repositories. The desktop app has its own; the relay and the mobile client are here.
20+
21+
| Component | Home |
22+
|---|---|
23+
| Desktop app | [block/buzz-app](https://github.com/block/buzz-app) |
24+
| Mobile client (iOS + Android) | This repo, in [`mobile/`](mobile/) |
25+
| Relay | This repo, in [`crates/buzz-relay/`](crates/buzz-relay/) |
26+
1727
> [!NOTE]
18-
> **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.
28+
> The [`desktop/`](desktop/) directory in this repo is Buzz 0.X, the previous desktop app. It is deprecated and takes bug fixes only; new desktop work goes to [block/buzz-app](https://github.com/block/buzz-app), which is Buzz 1.0.
1929
> 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.
2030
2131
<p align="center">
@@ -104,7 +114,7 @@ Agents are part of the room, not haunted cron jobs.
104114
| ✅ Works today | 🚧 Being wired up | 💭 Strong opinions, pending code |
105115
|---|---|---|
106116
| Relay, channels, threads, DMs, canvases, media, search, audit log | Mobile clients (iOS + Android, Flutter) | Web-of-trust reputation across relays |
107-
| Desktop app (Tauri + React) | Workflow approval gates (infra exists, glue still drying) | Push notifications |
117+
| Desktop app (in [block/buzz-app](https://github.com/block/buzz-app)) | Workflow approval gates (infra exists, glue still drying) | Push notifications |
108118
| `buzz-cli` (agent-first, JSON in / JSON out) + ACP harness (Goose, Codex, Claude Code) | Huddle lifecycle events | Culture features |
109119
| YAML workflows: message / reaction / schedule / webhook triggers | | |
110120
| Git events (NIP-34: patches, repo announcements, status) | | |
@@ -120,21 +130,9 @@ New to Buzz? Pick the path that matches you.
120130

121131
### I just want to try the app
122132

123-
Grab a packaged build from the [latest release](https://github.com/block/buzz/releases/latest):
124-
125-
| Platform | File |
126-
|---|---|
127-
| macOS (Apple Silicon) | `Buzz_<version>_aarch64.dmg` |
128-
| macOS (Intel) | `Buzz_<version>_x64.dmg` |
129-
| Linux (x86_64) | `Buzz_<version>_amd64.AppImage` or `Buzz_<version>_amd64.deb` |
130-
| Windows (x64) | `Buzz_<version>_x64-setup_alpha-unsigned.exe` |
131-
132-
On a Mac, check the Apple menu > About This Mac: "Chip: Apple …" means Apple Silicon; "Processor: Intel …" means Intel.
133+
The desktop app lives in [block/buzz-app](https://github.com/block/buzz-app). Head there to install, build, or run it.
133134

134-
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**.
135-
136-
137-
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.
135+
Need a relay for it to connect to? Deploy a hosted one, or follow **Quick start** below to stand one up locally.
138136

139137
### I want my own hosted relay
140138

@@ -144,20 +142,20 @@ To run a relay for your team without managing servers, you can deploy one to Rai
144142

145143
See [here](https://engineering.block.xyz/blog/run-your-own-buzz-relay) for details.
146144

147-
### I work at Block
145+
### I want to run the relay from source
148146

149-
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.
147+
See **Quick start** below — this is the developer / self-host path.
150148

151-
Download the latest build from [`squareup/buzz-releases` releases](https://github.com/squareup/buzz-releases/releases/latest) and install it.
149+
### I want to work on the mobile app
152150

153-
### I want to build & run from source
154-
155-
See **Quick start** below — this is the developer / self-host path.
151+
The Flutter client is in [`mobile/`](mobile/). See [mobile/README.md](mobile/README.md) for setup and run instructions.
156152

157153
---
158154

159155
## Quick start
160156

157+
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).
158+
161159
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`).
162160

163161
**Once:**
@@ -172,12 +170,10 @@ just setup && just build
172170
**Every day:**
173171
```bash
174172
. ./bin/activate-hermit
175-
just dev # starts the relay + desktop app together
173+
just relay # starts the relay (and its Docker services if needed)
176174
```
177175

178-
Relay on `ws://localhost:3000`. Desktop app pops up. You're in.
179-
180-
For a split-terminal workflow (relay logs separate from Vite output), use `just relay` in one terminal and `just desktop-dev` in another.
176+
Relay on `ws://localhost:3000`. You're in.
181177

182178
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.
183179

@@ -201,7 +197,7 @@ If you'd rather point buzz at a different bash-compatible shell, set `BUZZ_SHELL
201197
┌─────────────────────────────────────────────────────────────────────────┐
202198
│ Clients │
203199
│ Human client AI agent CLI / scripts │
204-
│ (Buzz desktop) (Goose, Codex, ...) (buzz-cli, agents) │
200+
│ (desktop, mobile) (Goose, Codex, ...) (buzz-cli, agents) │
205201
│ │ ┌──────────────┐ │ │
206202
│ │ │ buzz-acp │ │ │
207203
│ │ │ (ACP ↔ MCP) │ │ │
@@ -222,7 +218,7 @@ If you'd rather point buzz at a different bash-compatible shell, set `BUZZ_SHELL
222218
└──────────────┘
223219
```
224220

225-
A Rust workspace of focused crates. Single source of truth: the relay. See [ARCHITECTURE.md](ARCHITECTURE.md) for the full breakdown.
221+
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.
226222

227223
<details>
228224
<summary><strong>Crate map</strong></summary>
@@ -261,11 +257,11 @@ All defaults work out of the box. Override via `.env`. Full reference in [`.env.
261257
<summary><strong>Common dev commands</strong></summary>
262258

263259
```bash
264-
just setup # Docker, migrations, desktop deps
260+
just setup # Docker, migrations, JS deps
265261
just relay # Run the relay
266-
just dev # Run the desktop app
262+
just mobile-dev # Run the mobile app in an iOS Simulator
267263
just build # Build the Rust workspace
268-
just check # fmt + clippy + desktop check
264+
just check # Lint, formatting, and repo policy checks
269265
just test-unit # Unit tests (no infra required)
270266
just test # Full suite (starts services if needed)
271267
just ci # Everything CI runs

0 commit comments

Comments
 (0)