beads

package module
v0.54.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 2, 2026 License: MIT Imports: 3 Imported by: 0

README ¶

BeadsLog

Git-backed project memory that scales from solo developers to distributed AI agent teams.

BeadsLog extends Beads with automated session mapping, background enrichment, and lifecycle tracking. It turns natural language devlogs into a stateful, verifiable knowledge graph so agents never build on dead code or repeat historical mistakes.

🚀 Quick Start

Requires Go (1.24+).

# 1. Install
go install github.com/untoldecay/BeadsLog/cmd/bd@latest

# 2. Initialize in repo
bd init

# 3. Connect AI agent
bd onboard

🛠 Useful commands

Your agents handle the heavy lifting. As a human, you only need to know one command: Check all commands here.

  • Stay aligned: bd catchup (See what your team/agents completed since last checked)

🔄 The Agent Workflow

BeadsLog provides agents with dynamic context and architectural awareness, eliminating the need to guess or brute-force the repository.

Semantic Search & Exploration

Agents use specialized tools to map the project's evolution and dependencies:

  • search: FTS5-powered retrieval of historical decisions and narratives.
  • impact: Identifies all components semantically dependent on a target entity.
  • entities: Discovers the most significant architectural components by relationship density.
  • path: Traces the chain of events and sessions linking two disparate entities.
Stateful Iteration

Acquire context → Implement → Iterate → Record.

🎯 Use Cases

Goal Command
Resume Context bd devlog resume --last 1
Audit Architecture bd devlog impact "AuthService"
Team Sync bd catchup
Kill Experiments bd devlog abandon --scope branch:feature-x --message "..."
Trace Merges bd devlog search "modularization" --status active

📚 Docs

  • Use Cases — Real-world scenarios for agents and teams.
  • Project Catchup — Staying aligned with team progress.
  • Lifecycle States — Managing active, paused, and abandoned work.
  • Devlog — Understanding the "Bead" concept and the narrative format.
  • Devlog Architecture — How the background AI and crystallization engine works.
  • Ollama Enrichment — Configuring background semantic analysis.
  • Issue Architecture — Standard Beads data model and sync mechanism.
  • Hooks — Automating your workflow with Git integration.
  • Installation — Setup guide and platform requirements.

Documentation ¶

Overview ¶

Package beads provides a minimal public API for extending bd with custom orchestration.

Most extensions should use direct SQL queries against bd's database. This package exports only the essential types and functions needed for Go-based extensions that want to use bd's storage layer programmatically.

For detailed guidance on extending bd, see docs/EXTENDING.md.

Index ¶

Constants ¶

View Source 
const (
	StatusOpen       = types.StatusOpen
	StatusInProgress = types.StatusInProgress
	StatusBlocked    = types.StatusBlocked
	StatusDeferred   = types.StatusDeferred
	StatusClosed     = types.StatusClosed
)

Status constants

View Source 
const (
	TypeBug     = types.TypeBug
	TypeFeature = types.TypeFeature
	TypeTask    = types.TypeTask
	TypeEpic    = types.TypeEpic
	TypeChore   = types.TypeChore
)

IssueType constants

View Source 
const (
	DepBlocks            = types.DepBlocks
	DepRelated           = types.DepRelated
	DepParentChild       = types.DepParentChild
	DepDiscoveredFrom    = types.DepDiscoveredFrom
	DepConditionalBlocks = types.DepConditionalBlocks // B runs only if A fails (bd-kzda)
)

DependencyType constants

View Source 
const (
	SortPolicyHybrid   = types.SortPolicyHybrid
	SortPolicyPriority = types.SortPolicyPriority
	SortPolicyOldest   = types.SortPolicyOldest
)

SortPolicy constants

View Source 
const (
	EventCreated           = types.EventCreated
	EventUpdated           = types.EventUpdated
	EventStatusChanged     = types.EventStatusChanged
	EventCommented         = types.EventCommented
	EventClosed            = types.EventClosed
	EventReopened          = types.EventReopened
	EventDependencyAdded   = types.EventDependencyAdded
	EventDependencyRemoved = types.EventDependencyRemoved
	EventLabelAdded        = types.EventLabelAdded
	EventLabelRemoved      = types.EventLabelRemoved
	EventCompacted         = types.EventCompacted
)

EventType constants

Variables ¶

This section is empty.

Functions ¶

func FindBeadsDir ¶ 

func FindBeadsDir() string

FindBeadsDir finds the .beads/ directory in the current directory tree Returns empty string if not found. Supports both database and JSONL-only mode.

func FindDatabasePath ¶ 

func FindDatabasePath() string

FindDatabasePath finds the beads database in the current directory tree

func FindJSONLPath ¶ 

func FindJSONLPath(dbPath string) string

FindJSONLPath finds the JSONL file corresponding to a database path

Types ¶

type BlockedIssue ¶ 

type BlockedIssue = types.BlockedIssue

Core types from internal/types

type Comment ¶ 

type Comment = types.Comment

Core types from internal/types

type DatabaseInfo ¶ 

type DatabaseInfo = beads.DatabaseInfo

DatabaseInfo contains information about a beads database

func FindAllDatabases ¶ 

func FindAllDatabases() []DatabaseInfo

FindAllDatabases finds all beads databases in the system

type Dependency ¶ 

type Dependency = types.Dependency

Core types from internal/types

type DependencyCounts ¶ 

type DependencyCounts = types.DependencyCounts

Core types from internal/types

type DependencyType ¶ 

type DependencyType = types.DependencyType

Core types from internal/types

type EpicStatus ¶ 

type EpicStatus = types.EpicStatus

Core types from internal/types

type Event ¶ 

type Event = types.Event

Core types from internal/types

type EventType ¶ 

type EventType = types.EventType

Core types from internal/types

type Issue ¶ 

type Issue = types.Issue

Core types from internal/types

type IssueFilter ¶ 

type IssueFilter = types.IssueFilter

Core types from internal/types

type IssueType ¶ 

type IssueType = types.IssueType

Core types from internal/types

type IssueWithCounts ¶ 

type IssueWithCounts = types.IssueWithCounts

Core types from internal/types

type Label ¶ 

type Label = types.Label

Core types from internal/types

type RedirectInfo ¶ 

type RedirectInfo = beads.RedirectInfo

RedirectInfo contains information about a beads directory redirect

func GetRedirectInfo ¶ 

func GetRedirectInfo() RedirectInfo

GetRedirectInfo checks if the current beads directory is redirected. Returns RedirectInfo with IsRedirected=true if a redirect is active.

type SortPolicy ¶ 

type SortPolicy = types.SortPolicy

Core types from internal/types

type StaleFilter ¶ 

type StaleFilter = types.StaleFilter

Core types from internal/types

type Status ¶ 

type Status = types.Status

Core types from internal/types

type Storage ¶ 

type Storage = beads.Storage

Storage is the interface for beads storage operations

func NewSQLiteStorage ¶ 

func NewSQLiteStorage(ctx context.Context, dbPath string) (Storage, error)

NewSQLiteStorage creates a new SQLite storage instance at the given path

type Transaction ¶ 

type Transaction = beads.Transaction

Transaction provides atomic multi-operation support within a database transaction. Use Storage.RunInTransaction() to obtain a Transaction instance.

type TreeNode ¶ 

type TreeNode = types.TreeNode

Core types from internal/types

type WorkFilter ¶ 

type WorkFilter = types.WorkFilter

Core types from internal/types

Source Files ¶

View all Source files

Directories ¶

Path Synopsis
_LEGACY
beads-legacy/cmd/bd command
_rules
_evals command
cmd
bd command
Package main provides the CommandContext struct that consolidates runtime state.
 Package main provides the CommandContext struct that consolidates runtime state.
bd/doctor
Package doctor provides health check and repair functionality for beads.
 Package doctor provides health check and repair functionality for beads.
bd/doctor/fix
bd/setup
internal
audit
autoimport
beads
Package beads provides a minimal public API for extending bd with custom orchestration.
 Package beads provides a minimal public API for extending bd with custom orchestration.
changelog
compact
Package compact provides AI-powered issue compaction using Claude Haiku.
 Package compact provides AI-powered issue compaction using Claude Haiku.
config
configfile
daemon
debug
eval
export
extractor
formula
Package formula provides advice operators for step transformations.
 Package formula provides advice operators for step transformations.
git
hooks
Package hooks provides a hook system for extensibility.
 Package hooks provides a hook system for extensibility.
idgen
importer
linear
Package linear provides client and data types for the Linear GraphQL API.
 Package linear provides client and data types for the Linear GraphQL API.
lockfile
merge
molecules
Package molecules handles loading template molecules from molecules.jsonl catalogs.
 Package molecules handles loading template molecules from molecules.jsonl catalogs.
queries
recipes
Package recipes provides recipe-based configuration for bd setup.
 Package recipes provides recipe-based configuration for bd setup.
routing
rpc
storage
Package storage defines the interface for issue storage backends.
 Package storage defines the interface for issue storage backends.
storage/memory
Package memory implements the storage interface using in-memory data structures.
 Package memory implements the storage interface using in-memory data structures.
storage/sqlite
Package sqlite provides the blocked_issues_cache optimization for GetReadyWork performance.
 Package sqlite provides the blocked_issues_cache optimization for GetReadyWork performance.
storage/sqlite/migrations
syncbranch
Package syncbranch provides sync branch configuration and integrity checking.
 Package syncbranch provides sync branch configuration and integrity checking.
testutil
testutil/fixtures
Package fixtures provides realistic test data generation for benchmarks and tests.
 Package fixtures provides realistic test data generation for benchmarks and tests.
timeparsing
Package timeparsing provides layered time parsing for relative date/time expressions.
 Package timeparsing provides layered time parsing for relative date/time expressions.
types
Package types defines core data structures for the bd issue tracker.
 Package types defines core data structures for the bd issue tracker.
ui
Package ui provides terminal styling for beads CLI output.
 Package ui provides terminal styling for beads CLI output.
util
utils
Package utils provides utility functions for issue ID parsing and resolution.
 Package utils provides utility functions for issue ID parsing and resolution.
validation

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.