Skip to content

BERD TASK · 0022 · SAFEGUARD AND HAND OFF

Keep Berd current and report problems

Berd shipped three releases in five days in August and two more the following month. On macOS it updates itself; on other platforms you do. When something is wrong there are three documented ways to say so — only one of which, the GitHub issue, exists in the public build — and one thing not to do: open a pull request. The outcome of this task is a Berd that is current, a habit of reading what changed, and a bug report that lands where the team will read it.

Steps at a glance

  1. Let macOS update itself; update Windows and Linux by hand
  2. Read what changed before you restart
  3. Run Doctor when something is off
  4. Report a Berd problem by the first route that exists
  5. Send a harness problem to the harness
  6. Do not open a pull request

1. Let macOS update itself; update Windows and Linux by hand

The public macOS build checks a signed release feed in the background every few hours, downloads, and waits for you to restart; the update card in the system section of Settings shows the current version and a check-now action, and a beta channel can be chosen where the build offers one. A rollback is never a downgrade: if a release goes wrong the fix arrives as a newer patch.

[SCREENSHOT: T22-01 — the system settings with an update ready]

Windows and Linux builds are published on each versioned release with the updater switched off, so a new version is a fresh install of the versioned installer or package. Custom and locally built versions also do not update themselves. On any platform, the About subhead at the bottom of the system section gives the exact version for a report.

2. Read what changed before you restart

Several releases a week is normal and the release notes are short. Read the section for the version you are about to install — What changed in this Coach summarises each one in plain words and names the pages it touched — and look for the three kinds of line that change your morning: a feature that now needs confirmation, a setting that moved, a route that appeared or disappeared. Then restart.

3. Run Doctor when something is off

Doctor runs health checks on Berd, its agents and tools. Whether your build has it is supplied by the distribution's runtime configuration, and the sources do not say whether the public release ships it: look for a Doctor row in the system section of Settings, and if there is none, your build does not have it and the version line in step 1 plus the log paths in CONTRIBUTING.md are what you gather instead. Where it exists, it opens as a dialog from that row — not its own page, which older links and instructions may suggest. A failing check can offer a fix; Berd shows the command it would run and asks before running it. Copy report puts the result on the clipboard, which is exactly what a bug report wants. Doctor also reports the installed harness versions and where each came from, with an update prompt when a newer one exists.

[SCREENSHOT: T22-02 — Doctor with a run-fix prompt (builds that ship Doctor)]

4. Report a Berd problem by the first route that exists

Routes vary by build. In the v0.6.4 public release the in-app Send feedback action and the berdctl feedback command are compiled off (VITE_FEEDBACK=0 in the release workflow), so the route is the public issue tracker at github.com/block/berd/issues: pick a form (bug report or feature request), search first, reproduce on the current version, and file one issue per issue. An agent may help you draft it; you are the author and you post it. Since v0.6.3 Berd's own help checks whether the feedback command exists before suggesting it, which is why on a public build it sends you straight to GitHub.

In distributions that enable feedback (Block's internal build), two routes come first:

  1. berdctl feedback open --title … --description … opens the feedback form prefilled, and nothing is sent until you review and submit. Add --include-logs only if you want sanitised logs and diagnostics attached — they exclude prompts, responses, tool payloads and session databases.
  2. The in-app Send feedback action. Same form: title, description, up to a few images, the same opt-in logs.

[SCREENSHOT: T22-03 — the GitHub issue form (public build); Send feedback in distributions that enable it]

A good bug report reproduces from a fresh launch: what you clicked, which model and provider, whether the chat had history, expected versus actual, frequency, exact version and OS, and the relevant log lines — scrubbed, because logs carry paths, prompts and project names.

5. Send a harness problem to the harness

A hung turn, a tool that never returns, a model error: these belong to Goose, Claude, Codex or whichever harness the session runs on, and the feedback flow says so. The backend keeps its own logs under the Goose state directory. Berd's help is explicitly not the place for a harness's internal behaviour; see App vs harness.

6. Do not open a pull request

Berd is developed in the open by a small team at Block and pull requests from outside the team are closed automatically — a policy, not a judgement on the code. The way to participate is a well-formed issue. If you can build it locally, that is the best way to write one. Security problems go through private disclosure, never a public issue.

Last checked: Berd v0.6.4, 2026-09-11 — read from source and release notes, not yet tested in the app.

Learn more

Reference

Moment
change
Takes
untimed
Steps
6
Verified
Berd v0.6.4 · 2026-09-11 · source-read
NEVER BESTUCK AGAINCLICK ME

Guide built with Berd, Claude and Codex · verified against Berd v0.6.4, 2026-09-11 · read from source, not yet tested in the app · Buzz Guide · About · not affiliated with Block