Knowledge¶
Short articles on how Berd works and why it is built that way, plus the glossary. Each one ends with Do it: and the task it makes easier. Read the first five before anything else; the rest are for the moment a step surprises you.
-
What Berd is, and what it refuses to be
Berd is Block's open-source desktop app for working with AI agents. It runs on your own computer, holds your chats, projects, agents and skills in one place (and automations, in distributions that enable them — not the v0.6.4 public build), and lets you work across several models and several agent runtimes without switching apps. The agent itself is not Berd; Berd is the room the agent works in.
-
The Berd object model and its traps
Berd has a small number of things you can make, and the app is easier once you can name them. A session is one conversation with an agent; "chat" is the informal word for the same object. A project groups sessions around one or more working directories and sets how new chats start from them. A workspace is a folder, repo or worktree, held by a project or attached to a session. A worktree is a separate git working copy, created per chat when the project's policy says so.
-
App vs harness: where Berd stops
The model is the thing that thinks; the harness is the runtime that lets it act, holds the tools and the session, and talks to the model on your behalf. That distinction is the same in Berd as in Buzz, and the Buzz Guide's Model vs. harness explains it once for both. What this page adds is where Berd itself sits: above the harness, as the app around it.
-
Morgan, Berd's design lead, on Block's On The Block (September 2026), put the whole design idea in one line: everything under the hood is basically just a file. Agents and skills are markdown. Berd's job was to take those primitives, attach a mental model, and show them in an interface instead of a secret folder in Finder.
-
Berdy's own instructions say it in one line: agents are personalities you shape, each with its own instructions, style and face; not modes you toggle, more like characters you cast. That is the whole idea, and it is the same idea the Buzz Guide describes in Agents as colleagues, not bots. What differs in Berd is that these colleagues have no identity of their own, no channel membership and no audit trail; they are files on your laptop, and Berd's built-in agents describes the ten that ship with it.
-
Skills: three sources and one precedence rule
A skill is the same thing in Berd as in Buzz: written instructions, saved as a file, that an agent picks up when the work calls for it. The Buzz Guide's What a skill is explains the idea; this page covers only what Berd adds, which is where skills come from and which one wins.
-
Berd has no single "memory" feature. Berdy's instructions describe tailoring as a spectrum, and the job is to find the right home for each durable thing you notice about how you work. There are four homes:
-
The Home canvas as a working surface
Home is a spatial canvas of pinned things, not a dashboard. Right-click it and you can pin a clock, a photo, a sticky note, a checklist, a text label, and any of the objects you actually work with: an agent, a chat, a project or a skill (and, in distributions that enable automations — not the v0.6.4 public build — the latest output of an automation). Since v0.6.3 new installs start with a refined layout and you can add labels, in five typefaces, to name areas of the canvas. Two experiments extend it: pinned chats that expand into live cards, and saved prompts pinned to Home that run with one click.
-
Queue, steer and dispatch, in plain terms
While an agent is working, or while a chat is still starting, anything you send is not lost and not sent yet. It is queued. Berd's rules for the composer are written as laws, and the laws say: every accepted message goes into that chat's queue in the order you sent it, even before the session is ready; nothing is dispatched until the session can process it; and nothing jumps ahead of a message queued before it.
-
A model can only hold so much of a conversation at once: the context window, measured in tokens. Berd shows how full it is in the chat toolbar as a ring and a count, {tokens} / {limit} tokens used, with how much is left. When a session runs long, the window fills with earlier messages, tool output and file contents, and something has to give.
-
Provider errors mean four things
A provider is the credentialed connection between a model and Berd. When you save a provider's credentials, Berd immediately fetches that provider's live list of models. That fetch is not decoration: it is the verification. It checks the key, the URL and the network in one request, so if the model list appears, the provider works.
-
Automations: built by talking, failing in two places
An automation is a saved, re-runnable task with its own builder, run history and detail view. What sets it apart from a form is how it is made: you describe what you want in a builder chat, the builder drafts and revises with you, and then you approve the draft into a real, savable tile. Only then does it have a schedule and a history.
-
Connections, extensions and who manages them
Berd has two different ways to give an agent reach into the world, and they share one settings surface, which is why they get confused.
-
Berd is a local app, and most of what it holds never leaves your machine. But "local" is not "nothing leaves", and for a consultant carrying client material the useful question is: which things leave, to whom, and which things stay, where?
-
Berd moves fast: reading a release
Five releases in four weeks: v0.6.0 on 14 August 2026, v0.6.1 three days later, v0.6.2 the day after, v0.6.3 on 5 September (published on the 8th), and v0.6.4 two days after that. Berd's own help skill is built around this pace: it tells the help agent to name where to look rather than labels, sections and flags, because those are the details most likely to move, and to treat its own reference files as hints, not guarantees.
-
Start alone, then go multiplayer
Block makes two agent products and describes the pair in four words: start alone, then go multiplayer. The phrase comes from Block's article on designing Berd, published 2026-08-18. Berd is the private workspace on your own computer, where one person works with agents. Buzz is the shared workspace, where people and agents work together in the same rooms, and every message is signed and kept.
-
What survives the trip to Buzz
The day a piece of work goes multiplayer, "move it to Buzz" turns out not to be one move. A Berd workspace is several kinds of object, and each travels differently — some as files, some as rebuilds, one not at all. Knowing the manifest before you pack is the difference between an afternoon's move and quietly losing things.
-
Code archaeology: agents and skills
A name in the code is a lead, not an installed feature. The September 2026 audit followed agent and skill references through Berd, Buzz and Goose, then checked the relevant history. Some apparent gaps were real recoveries. Others were renamed files, examples, private dependencies or ideas that never became standalone prompts.
-
The words Berd uses, condensed from its own help references, bundled skills, laws and interface strings, with the closest Buzz equivalent where one exists. Where Berd and Buzz mean the same thing by a word, the Buzz Guide article is linked rather than re-explained. A dash in the last column means Buzz has no counterpart; that is usually the point, not a gap.
Also here¶
- What changed — release by release, and which pages are now behind
- Keyboard shortcuts — the ones the app's own strings name