Skip to content

SUPPORTING KNOWLEDGE · 0002

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.

Then the things that shape what an agent does: an agent is a saved configuration (name, avatar, provider and model, instructions) stored as one markdown file; a skill is a folder with a SKILL.md that is loaded when it fits your request; an automation is a saved, re-runnable task with a schedule and a run history, built by chatting — in distributions that enable it; the v0.6.4 public build compiles automations off. Beside a conversation: an artifact is a file opened from the session into the side viewer, and the right rail is the session's context panel (workspaces, changes, artifacts, terminal).

The names above have held across releases; the buttons around them move.

Why it matters to you

Most confusion in Berd is one object being mistaken for another. The help skill's reference files list the traps directly:

  • A project is not a session. A project's standing description is given to every chat in it; a session's attachments belong to that session only. The right rail shows what is attached to this chat. "Where did my files go?" is nearly always a question about which workspace this session has.
  • Active and archived are different places. An active project lives in the Projects view; an archived one is found in Settings.
  • Archive is reversible; delete is not. The delete confirmation says you will lose all context and memory associated with the project. Sending a message to an archived chat restores it (v0.6.4); nothing restores a deleted project.
  • A Goose-created worktree is Berd's to delete. Removing an ordinary workspace from a chat leaves the files on disk. Removing a worktree Goose created deletes it, uncommitted changes included, and the confirmation says so.
  • An agent is not a mode. It is a file with instructions. See Agents are cast, not modes.

One thing the sources leave open: the project dialog has both a "What should the agent know about this project?" field and an Instructions field with a system-prompt placeholder. Whether these are one control renamed or two is not verified.

How to apply it

Name the object before you act. "Archive this" means a session or a project, and they live in different places afterwards. "Put this folder in the conversation" means attaching a workspace to the session, not adding it to the project.

Give ongoing work a project and let the description carry the standing context, so you stop pasting the same preamble into every chat.

Read every confirmation that mentions a worktree or a branch. The wording tells you whether files stay on disk.

In Buzz the closest equivalents are a thread for a session, a channel for a project and a workflow for an automation; Buzz or Berd carries the full mapping.

If you ignore this

You archive a project and then search the Projects view for it. You attach a repo to one chat and expect the next chat to see its changes rail. Or you remove a worktree and lose a morning's uncommitted edits, having clicked through a dialog that named the loss.

Examples

A folder (project) holds many conversations (sessions); each conversation has papers on the desk beside it (workspaces and artifacts); the desk is cleared when that conversation ends, not when the folder is closed.

An engagement project with the client's repo and a notes/ folder, worktree policy set to ask, and a description naming the house style. Every new chat starts with that context; each chat's rail shows only what that chat attached.

Treating "chat" and "session" as two features and looking for the setting that turns one into the other. They are one object under two names.

Do it: Create a project around your folders

Last checked: Berd v0.6.4, 2026-09-11.

Reference

Verified
Berd v0.6.4 · 2026-09-11
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