Core Concepts

Workspace

A workspace is a project directory that contains a .beads/ folder. The database backend can be SQLite (legacy) or Dolt. Each workspace tracks its own set of issues, independent of other projects.

Beadbox detects workspaces from the registry at ~/.beadbox/registry.json, a cookie tracking your last active workspace, and scanning the current working directory for .beads/ folders. Switch between workspaces using the selector in the header.

In embedded mode, all data stays local with no account or cloud dependency. A workspace can optionally connect to a remote Dolt server for multi-writer access, which enables push and pull synchronization.

Bead

A bead is the fundamental unit of work: an issue, task, or ticket. Every bead has:

• A unique ID (e.g., bb-a3f2) assigned by the bd CLI, using a workspace prefix and base32-encoded suffix
• A title and optional description (markdown supported)
• Status: open, in_progress, blocked, deferred, ready_for_qa, qa_passed, ready_to_ship, or closed
• Priority: P0 (critical) through P4 (backlog)
• Type: task, bug, feature, epic, chore, or decision (core types). Custom types like molecule and gate can be configured per workspace.
• An optional assignee

Create beads with bd create and view them with bd show. In Beadbox, click any bead in the tree to open its detail panel.

Epic

An epic is a bead with children. It groups related work and tracks aggregate progress. In the tree view, epics show a progress bar based on how many children are closed.

Create a child by passing --parent:

bd create --title="Subtask" --type=task --parent=EPIC-ID

Epics can nest. A child of an epic can itself be an epic with its own children. The tree view renders this hierarchy with expand/collapse controls.

Dependency

A bead can block other beads. When bead A blocks bead B, B cannot proceed until A is closed. Dependencies appear as blocker badges in the tree view and as a dependency list in the detail panel.

Set a dependency with bd dep:

bd dep BEAD-A --blocks BEAD-B

Beadbox draws the dependency graph so you can see at a glance which beads are blocking progress.

Comment

Every bead has a comment thread. Comments are how agents and humans communicate about a bead: posting plans before implementation, reporting completion, flagging blockers, and providing QA verification steps.

Add a comment from the CLI:

bd comments add BEAD-ID --author agent-name "PLAN: ..."
bd comments add BEAD-ID --author agent-name "DONE: ..."

In Beadbox, comments render as markdown in the detail panel, ordered chronologically.

Status Lifecycle

Every bead follows this lifecycle:

Each status has a distinct color badge in Beadbox. The filter bar lets you show or hide beads by status. The Activity Dashboard groups beads by pipeline stage using these statuses.