Callers that need ready work across several statuses (e.g. Gas City's
native store Ready(), which spans open/blocked/deferred/pinned/hooked/
review/testing) currently issue one GetReadyWork per status. Each call
re-pays the deferred-parents pre-query, the wisps arm, and the
per-transaction round trips — measured at 30-70ms per call on a live
server-mode store, ~7x per Ready().
WorkFilter.Statuses (OR semantics) renders a single status IN (...)
clause through BuildReadyWorkWhere and propagates to the wisp-side
IssueFilter.Statuses, so multi-status callers pay the fixed per-call
work once. Singular Status keeps precedence; both empty keeps the
legacy ('open', 'in_progress') default.
Review round 2: a conformance audit case (ReadyMultiStatusFilter) pins
the contract at the result level against both backends — real issues
and wisps across several statuses, OR semantics in one call, singular-
Status precedence, the empty default, a custom status through the same
IN clause, and the ephemeral exclusion of wisps without
IncludeEphemeral. The library guide documents Statuses, and
BuildReadyWorkWhere computes the status clause and args in one pass.
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
7.1 KiB
Beads Library Usage Example
This example demonstrates using Beads as a Go library in external projects (like VC).
Why Use Beads as a Library?
Instead of spawning bd CLI processes:
- ✅ Direct API access - Call functions directly instead of parsing JSON output
- ✅ Type safety - Compile-time checking of types and interfaces
- ✅ Performance - No process spawn overhead
- ✅ Transactions - Access to database transactions for complex operations
- ✅ Shared database - Multiple components can use same database connection
- ✅ Error handling - Proper Go error types instead of parsing stderr
Installation
In your Go project:
go get github.com/steveyegge/beads@latest
Basic Usage
package main
import (
"context"
"log"
"github.com/steveyegge/beads"
)
func main() {
ctx := context.Background()
// Find the workspace and open its configured Dolt implementation
beadsDir := beads.FindBeadsDir()
store, err := beads.OpenBestAvailable(ctx, beadsDir)
if err != nil {
log.Fatal(err)
}
defer store.Close()
// Get ready work
ready, err := store.GetReadyWork(ctx, beads.WorkFilter{
Status: beads.StatusOpen,
Limit: 10,
})
if err != nil {
log.Fatal(err)
}
// Process ready issues...
}
Filtering ready work by status
WorkFilter offers two status fields:
Statusfilters to exactly one status.Statusesfilters to any of the given statuses (OR semantics) in a single query, so multi-status callers avoid oneGetReadyWorkround trip per status. Custom statuses participate like built-ins.
Status takes precedence: when it is set, Statuses is ignored. When both
are empty, the default of ('open', 'in_progress') applies.
// One query for open OR blocked ready work
ready, err := store.GetReadyWork(ctx, beads.WorkFilter{
Statuses: []beads.Status{beads.StatusOpen, beads.StatusBlocked},
Limit: 10,
})
Running This Example
# From this directory
cd examples/library-usage
# Make sure there's a Beads database
bd init --prefix demo
# Run the example
go run main.go
Available Operations
The beads.Storage interface provides:
Issues
CreateIssue(ctx, issue, actor)- Create a new issueCreateIssues(ctx, issues, actor)- Batch create issuesGetIssue(ctx, id)- Get issue by IDUpdateIssue(ctx, id, updates, actor)- Update issue fieldsUpdateIssueChecked(ctx, id, updates, actor, opts)- Update with an optional optimistic-concurrency (CAS) precondition (opts.ExpectedVersion); see Concurrency belowCloseIssue(ctx, id, reason, actor)- Close an issueSearchIssues(ctx, query, filter)- Search with filters
Dependencies
AddDependency(ctx, dep, actor)- Add dependency between issuesRemoveDependency(ctx, issueID, dependsOnID, actor)- Remove dependencyGetDependencies(ctx, issueID)- Get what this issue depends onGetDependents(ctx, issueID)- Get what depends on this issueGetDependencyTree(ctx, issueID, maxDepth, showAllPaths)- Visualize tree
Labels
AddLabel(ctx, issueID, label, actor)- Add label to issueRemoveLabel(ctx, issueID, label, actor)- Remove labelGetLabels(ctx, issueID)- Get all labels for an issueGetIssuesByLabel(ctx, label)- Find issues with label
Ready Work & Blocking
GetReadyWork(ctx, filter)- Find issues with no blockersGetBlockedIssues(ctx)- Find blocked issues with blocker infoGetEpicsEligibleForClosure(ctx)- Find completable epics
Comments & Events
AddIssueComment(ctx, issueID, author, text)- Add commentGetIssueComments(ctx, issueID)- Get all commentsGetEvents(ctx, issueID, limit)- Get audit trail
Statistics
GetStatistics(ctx)- Get aggregate metrics
Concurrency & Metadata
UpdateIssueChecked(ctx, id, updates, actor, opts)- LikeUpdateIssue, but whenopts.ExpectedVersionis set the update proceeds only if the issue's currentRowVersionstill matches, else it refuses withbeads.ErrVersionMismatch. The version read and the write share one transaction (a true compare-and-swap).RowVersionis surfaced read-only onIssuereads.MergeMetadata(ctx, issueID, key, value, actor)- Atomically merge a single key into an issue's metadata JSON. Two concurrent merges of different keys both survive rather than clobbering each other.
Implementer note (interface change):
UpdateIssueCheckedandMergeMetadataare now required methods on thebeads.Storageinterface. Code that only consumesbeads.Storageneeds no change, but any external type that implementsbeads.Storage(a custom store, mock, or proxy) must add these two methods to compile. If you only need the base behavior,UpdateIssueCheckedwith a nilopts.ExpectedVersionis identical toUpdateIssue, andMergeMetadatacan be layered over a read-modify-write of the issue's metadata.
Types
All types are exported via the beads package:
// Core types
beads.Issue
beads.Status (Open, InProgress, Closed, Blocked)
beads.IssueType (Bug, Feature, Task, Epic, Chore)
beads.Priority (0-4)
// Relationships
beads.Dependency
beads.DependencyType (Blocks, Related, ParentChild, DiscoveredFrom)
// Metadata
beads.Label
beads.Comment
beads.Event
// Queries
beads.IssueFilter
beads.WorkFilter
beads.BlockedIssue
beads.EpicStatus
beads.Statistics
VC Integration Example
For VC (VibeCoder), the integration would look like:
// In VC's storage layer
type VCStorage struct {
beads beads.Storage
}
func NewVCStorage(ctx context.Context, beadsDir string) (*VCStorage, error) {
store, err := beads.OpenBestAvailable(ctx, beadsDir)
if err != nil {
return nil, err
}
return &VCStorage{beads: store}, nil
}
// Claim ready work for executor
func (s *VCStorage) ClaimWork(ctx context.Context, executorID string) (*beads.Issue, error) {
ready, err := s.beads.GetReadyWork(ctx, beads.WorkFilter{
Status: beads.StatusOpen,
Limit: 1,
})
if err != nil {
return nil, err
}
if len(ready) == 0 {
return nil, nil // No work available
}
issue := ready[0]
// Claim it
updates := map[string]interface{}{
"status": beads.StatusInProgress,
"assignee": executorID,
}
if err := s.beads.UpdateIssue(ctx, issue.ID, updates, executorID); err != nil {
return nil, err
}
return issue, nil
}
Best Practices
- Context - Always pass
context.Contextfor cancellation support - Actor - Provide meaningful actor strings for audit trail
- Error handling - Check all errors; database operations can fail
- Close - Always
defer store.Close()after opening - Transactions - For complex multi-step operations, consider using the underlying database connection directly
See Also
- bd-example-extension-go - Legacy SQLite extension example
- beads.go - Public API source
- internal/storage/storage.go - Storage interface