beads

README

bd - Beads

Distributed graph issue tracker for AI agents, powered by Dolt.

Platforms: macOS, Linux, Windows, FreeBSD

Docs: https://beads.gascity.com/

Beads provides a persistent, structured memory for coding agents. It replaces messy markdown plans with a dependency-aware graph, allowing agents to handle long-horizon tasks without losing context.

flowchart LR
    create["bd create<br/>new bead"] --> depgraph["dependency<br/>graph"]
    depgraph --> ready["bd ready<br/>claimable work"]
    ready --> claim["bd update --claim<br/>agent takes it"]
    claim --> close["bd close<br/>work done"]
    close -->|blockers released| ready
    depgraph <-->|"bd dolt push / pull"| remote[("other machines<br/>and agents")]

⚡ Quick Start

# Install beads CLI (system-wide - don't clone this repo into your project)
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash

# Initialize in YOUR project
cd your-project
bd init

# Optional: refresh or install richer instructions for your agent
bd setup codex    # Codex CLI - installs skill, AGENTS.md guidance, and hooks
bd setup claude   # Claude Code - installs hooks/settings
bd setup factory  # Factory.ai Droid - creates/updates AGENTS.md

Note: Beads is a CLI tool you install once and use everywhere. You don't need to clone this repository into your project.

bd init creates or updates AGENTS.md by default so agents can discover the beads workflow, and also installs project Claude/Codex integrations unless you pass --skip-agents or --stealth. Use bd setup --list to see supported integrations, including bd setup codex, bd setup factory, bd setup claude, bd setup mux, bd setup cursor, and more. See Agent and IDE setup.

Manual copy-paste is only for unsupported agents, existing projects where you cannot rerun bd init/bd setup, or custom instruction files. In those cases, run bd onboard and paste the printed snippet into the file your agent reads.

If your agent is not covered by bd setup, add this minimal AGENTS.md section:

This project uses bd (beads) for issue tracking.

- Run `bd prime` for workflow context and command guidance.
- Use `bd ready`, `bd show <id>`, `bd update <id> --claim`, and `bd close <id>`.
- Use `bd remember "insight"` for persistent project memory; do not create MEMORY.md files.
- Do not use markdown TODO lists for task tracking.

🛠 Features

• Dolt-Powered: Version-controlled SQL database with cell-level merge, native branching, and built-in sync via Dolt remotes.
• Agent-Optimized: JSON output, dependency tracking, and auto-ready task detection.
• Zero Conflict: Hash-based IDs (bd-a1b2) prevent merge collisions in multi-agent/multi-branch workflows.
• Compaction: Semantic "memory decay" summarizes old closed tasks to save context window.
• Messaging: Message issue type with threading (--thread), ephemeral lifecycle, and mail delegation.
• Graph Links: relates-to, duplicates, supersedes, and replies-to for knowledge graphs.

📖 Essential Commands

Command	Action
bd ready	List tasks with no open blockers.
bd create "Title" -p 0	Create a P0 task.
bd update <id> --claim	Atomically claim a task (sets assignee + in_progress).
bd dep add <child> <parent>	Link tasks (blocks, related, parent-child).
bd show <id>	View task details and audit trail.
bd prime	Print agent workflow context and persistent memories.
bd remember "insight"	Store project memory that bd prime injects later.

🔗 Hierarchy & Workflow

Beads supports hierarchical IDs for epics:

• bd-a3f8 (Epic)
• bd-a3f8.1 (Task)
• bd-a3f8.1.1 (Sub-task)

Stealth Mode: Run bd init --stealth to use Beads locally without committing files to the main repo. Perfect for personal use on shared projects. See Git-Free Usage below.

Contributor vs Maintainer: When working on open-source projects:

• Contributors (forked repos): Run bd init --contributor to route planning issues to a separate repo (e.g., ~/.beads-planning). Keeps experimental work out of PRs.
• Maintainers (write access): Beads auto-detects maintainer role via SSH URLs or HTTPS with credentials. Only need git config beads.role maintainer if using GitHub HTTPS without credentials but you have write access.

📦 Installation

brew install beads           # macOS / Linux (recommended)
npm install -g @beads/bd     # Node.js users

Other methods: install script | go install | from source | Windows | Arch AUR

Requirements: macOS, Linux, Windows, or FreeBSD. See docs/getting-started/installation.md for complete installation guide.

Upgrading? Replacing the binary is not always the whole story. Short version: sync remote-backed databases with your current bd, back up with bd export --all, upgrade the binary, then run bd info --whats-new, bd hooks install, and bd version. If the upgrade crosses a schema migration on a remote-backed database, exactly one designated clone runs bd migrate and bd dolt push; other clones install the new binary and run bd bootstrap. See the full upgrade guide or docs/getting-started/installation.md.

Security And Verification

Before trusting any downloaded binary, verify its checksum against the release checksums.txt.

The install scripts verify release checksums before install. For manual installs, do this verification yourself before first run.

On macOS, scripts/install.sh preserves the downloaded signature by default. Local ad-hoc re-signing is explicit opt-in via BEADS_INSTALL_RESIGN_MACOS=1.

See docs/reference/antivirus.md for Windows AV false-positive guidance and verification workflow.

💾 Storage Modes

Beads uses Dolt as its database. Two modes:

• Embedded (default) — bd init. Dolt runs in-process, data lives in .beads/embeddeddolt/, single writer. Recommended for most users.
• Server — bd init --server. Connects to an external dolt sql-server for multiple concurrent writers; data lives in .beads/dolt/.

Cross-machine sync uses bd dolt push / bd dolt pull against refs/dolt/data on your git remote; .beads/issues.jsonl is an export for viewers and interchange, not the source of truth or a backup. Back up and migrate between modes with bd backup; reclaim space with bd prune / bd purge.

Full detail — connection flags, sockets, maintenance, backup, and migration — in the Dolt backend guide.

Schema Version Guard

bd checks the database schema version at open time. If the database has been migrated by a newer binary and an older binary tries to open it, bd exits with an actionable error rather than issuing queries that fail with cryptic SQL errors:

schema version mismatch: database is at v45, binary knows up to v42 (3 migrations ahead)

  Your bd binary is stale. Queries for dropped or renamed columns will fail
  with cryptic SQL errors (e.g. "column X could not be found in any table in scope").

  Rebuild from main:
    CGO_ENABLED=0 go build -tags gms_pure_go ./cmd/bd

  Or install the latest release:
    CGO_ENABLED=0 go install -tags gms_pure_go github.com/steveyegge/beads/cmd/bd@latest

  To proceed despite the risk (some read commands may still work):
    BD_IGNORE_SCHEMA_SKEW=1 bd <command>
    bd --ignore-schema-skew <command>

When this fires: only when the database schema is ahead of the binary (a newer binary migrated the database; this binary doesn't know those migrations). Normal upgrades, where the binary migrates the database forward, are unaffected.

Escape hatch: BD_IGNORE_SCHEMA_SKEW=1 (or --ignore-schema-skew) bypasses the guard with a warning on stderr. Use this only if you know the forward migrations are additive and safe for your specific workload.

🌐 Community Tools

See docs/community-tools.md for a curated list of community-built UIs, extensions, and integrations—including terminal interfaces, web UIs, editor extensions, and native apps.

See docs/related-projects.md for adjacent or complementary projects that solve different problems in the same neighborhood.

🚀 Git-Free Usage

Beads works without git. The Dolt database is the storage backend — git integration (hooks, repo discovery, identity) is optional.

# Initialize without git
export BEADS_DIR=/path/to/your/project/.beads
bd init --quiet --stealth

# All core commands work with zero git calls
bd create "Fix auth bug" -p 1 -t bug
bd ready --json
bd update bd-a1b2 --claim
bd prime
bd close bd-a1b2 "Fixed"

BEADS_DIR tells bd where to put the .beads/ database directory, bypassing git repo discovery. --stealth sets no-git-ops: true in config, disabling all git hook installation and git operations.

This is useful for:

• Non-git VCS (Sapling, Jujutsu, Piper) — no .git/ directory needed
• Monorepos — point BEADS_DIR at a specific subdirectory
• CI/CD — isolated task tracking without repo-level side effects
• Evaluation/testing — ephemeral databases in /tmp

📝 Documentation

• Documentation site | Installing | Sync Concepts | Agent Workflow | Copilot CLI Setup | Copilot VS Code MCP | Articles | Sync Branch Mode | Troubleshooting | FAQ
• 

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 a working extension example, see examples/bd-example-extension-go.

This is the CONSUMER surface: it opens and uses bd's own storage. To IMPLEMENT a storage backend out of tree — and prove it with the conformance suite — use github.com/steveyegge/beads/backend and github.com/steveyegge/beads/backend/conformance instead.

Index

• Constants
• Variables
• func AllowSharedSchemaMigration(allow bool)
• func FindBeadsDir() string
• func FindDatabasePath() string
• type BlockedIssue
• type BlockedQuerier
  • func AsBlockedQuerier(s Storage) (BlockedQuerier, bool)
• type ClaimConflict
  • func ParseClaimConflict(err error) (ClaimConflict, bool)
• type CloseIssueOptions
• type CloseIssueResult
• type Comment
• type CommentPageCursor
• type CommitInfo
• type Conflict
• type DatabaseInfo
  • func FindAllDatabases() []DatabaseInfo
• type Dependency
• type DependencyAddOptions
• type DependencyCounts
• type DependencyEndpointNotFoundError
• type DependencyHierarchyConflictError
• type DependencyRemoveOptions
• type DependencyType
• type DependencyTypeConflictError
• type DependentQuerier
  • func AsDependentQuerier(s Storage) (DependentQuerier, bool)
• type EpicStatus
• type ErrUnsupported
• type Event
• type EventCursor
• type EventQuerier
  • func AsEventQuerier(s Storage) (EventQuerier, bool)
• type EventType
• type Issue
• type IssueClaimer
  • func AsIssueClaimer(s Storage) (IssueClaimer, bool)
• type IssueFilter
• type IssueType
• type IssueWithCounts
• type IssueWithDependencyMetadata
• type Label
• type RedirectInfo
  • func GetRedirectInfo() RedirectInfo
• type RemoteInfo
• type RemoteStore
• type SortPolicy
• type StaleFilter
• type Status
• type StatusEntry
• type Storage
  • func Open(ctx context.Context, dbPath string) (Storage, error)
  • func OpenBestAvailable(ctx context.Context, beadsDir string) (Storage, error)
  • func OpenFromConfig(ctx context.Context, beadsDir string) (Storage, error)
  • func OpenGated(ctx context.Context, beadsDir string, wait time.Duration) (Storage, error)
• type SyncResult
• type SyncStatus
• type SyncStore
• type Transaction
• type TreeNode
• type UpdateIssueOptions
• type VCStatus
• type VersionControlReader
• type WispFilter
• type WorkFilter

Constants

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

Status constants

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

IssueType constants

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

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

SortPolicy constants

const (
	EventCreated           = types.EventCreated
	EventUpdated           = types.EventUpdated
	EventClaimed           = types.EventClaimed
	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

const MaxFieldLen = types.MaxFieldLen

MaxFieldLen re-exports the maximum length (in characters) of the assignee, owner, and label fields, paired with the ErrFieldTooLong sentinel below.

Variables

var (
	ErrCircuitOpen         = dolt.ErrCircuitOpen
	ErrCommitIndeterminate = storage.ErrCommitIndeterminate
)

ErrCircuitOpen is re-exported (aliased, so errors.Is works across the package boundary) from the Dolt storage layer: a read or write rejected because the Dolt circuit breaker is open wraps it. The claim sentinels ErrAlreadyClaimed and ErrNotClaimable — the ones ParseClaimConflict recovers assignee/status detail from — are re-exported with the other error sentinels below.

var (
	ErrNotFound        = storage.ErrNotFound
	ErrAlreadyClaimed  = storage.ErrAlreadyClaimed
	ErrNotClaimable    = storage.ErrNotClaimable
	ErrCloseBlocked    = storage.ErrCloseBlocked
	ErrVersionMismatch = storage.ErrVersionMismatch
	ErrSelfDependency  = domain.ErrSelfDependency
	ErrDependencyCycle = domain.ErrDependencyCycle
	// ErrDependencySourceNotFound and ErrDependencyTargetNotFound are the two
	// endpoint-existence refusals AddDependency and AddDependencies raise; the
	// typed value carrying the missing id is DependencyEndpointNotFoundError.
	ErrDependencySourceNotFound = domain.ErrDependencySourceNotFound
	ErrDependencyTargetNotFound = domain.ErrDependencyTargetNotFound
	ErrFieldTooLong             = types.ErrFieldTooLong
	// ErrGateBusy is returned by OpenGated when a maintenance operation
	// holds the workspace or physical-root gate exclusively and the wait
	// budget ran out. Alias of the internal sentinel so errors.Is works
	// across the package boundary.
	ErrGateBusy = workspacegate.ErrBusy
)

Re-exported error sentinels so consumers match on errors.Is rather than on message text. Each is an ALIAS of the internal sentinel, so the identity is preserved across the package boundary.

Functions

func AllowSharedSchemaMigration

func AllowSharedSchemaMigration(allow bool)

AllowSharedSchemaMigration authorizes this process to apply pending schema migrations to a database that is SHARED with other bd clients — a Dolt sql-server, where migrating promotes the schema version for every connected client at once and clients still running an older bd will refuse the database until they are upgraded (gastownhall/beads#5920).

Without it, an embedder that upgrades its beads dependency across a schema bump gets a migration-gate error from every writable Open* call, whose guidance names CLI commands (`bd migrate schema`) that mean nothing inside a library process. This is the programmatic equivalent of that command.

It is process-local and set-or-clear, which is the point: the alternative — os.Setenv("BD_ALLOW_REMOTE_MIGRATE", "1") — is process-GLOBAL and inherited by every child process the embedder spawns, including git hooks and dolt subprocesses.

The parity with that env var is only in the process-local mechanism, not the reach: BD_ALLOW_REMOTE_MIGRATE=1 unlocks BOTH the no-remote and the remote-backed shared arms, while this authorizes ONLY the no-remote arm. A remote-backed shared store still needs --force / AllowRemoteMigrateEnv, because #4259 cross-clone coordination is a stronger, different contract.

Call it before the Open* call that should perform the migration, and clear it afterwards. Only grant it once the operator has confirmed that every other client of the server is upgraded; it is a coordination decision the library cannot make, because other clients' versions are not observable from this process.

Embedded (single-writer) databases never need it: they still auto-migrate.

func FindBeadsDir

func FindBeadsDir() string

FindBeadsDir finds the .beads/ directory in the current directory tree. Returns empty string if not found.

func FindDatabasePath

func FindDatabasePath() string

FindDatabasePath finds the beads database in the current directory tree

Types

type BlockedIssue

type BlockedIssue = types.BlockedIssue

Core types from internal/types

type BlockedQuerier

type BlockedQuerier interface {
	// IsBlocked reports whether issueID is blocked (its denormalized transitive
	// is_blocked flag) and the open direct blockers for display.
	IsBlocked(ctx context.Context, issueID string) (bool, []string, error)
	// IsBlockedBatch returns the denormalized transitive is_blocked flag for each
	// of ids in one batched read. ids present in neither the issues nor wisps
	// table are absent from the map; callers treat absent as not-blocked.
	IsBlockedBatch(ctx context.Context, ids []string) (map[string]bool, error)
}

BlockedQuerier is the transitive-blocked surface of a Storage: the denormalized is_blocked flag, single or batched. Like EventQuerier it is a NARROW hand-declared root interface (not an alias of DependencyQueryStore), exposing only the reads consumers use. IsBlockedBatch returns the is_blocked column for a whole page in one round-trip — the same transitive value IsBlocked returns per id, with no N-call fan-out. Reach it via AsBlockedQuerier.

func AsBlockedQuerier

func AsBlockedQuerier(s Storage) (BlockedQuerier, bool)

AsBlockedQuerier returns the BlockedQuerier view of s, or (nil, false) when the backing store does not expose the transitive-blocked reads. Assert once and fail loud. A single direct assertion is sufficient — see the decorator contract on AsIssueClaimer.

type ClaimConflict

type ClaimConflict struct {
	// CurrentAssignee is the actor currently holding the issue. Set when the
	// error wraps ErrAlreadyClaimed and the assignee was parseable.
	CurrentAssignee string
	// CurrentStatus is the issue's status that made it unclaimable. Set when
	// the error wraps ErrNotClaimable and the status was parseable.
	CurrentStatus string
}

ClaimConflict describes why a claim failed, recovered from the claim error.

The engine's claim path embeds the conflicting state in the message: on ErrAlreadyClaimed the current assignee ("issue already claimed by <assignee>"), on ErrNotClaimable the current status ("issue not claimable: status <status>"). ClaimConflict carries whichever of those was recoverable; the other stays empty. This is a deliberately string-coupled shim.

A CALLER ON THE LIBRARY CONTRACT DOES NOT NEED IT. The claim path now returns issueops.ClaimConflictError, which carries the assignee and status as typed fields read inside the attempt that lost, so errors.As recovers them without parsing anything. This shim stays for callers holding a claim error from somewhere else, and because it is public API.

func ParseClaimConflict

func ParseClaimConflict(err error) (ClaimConflict, bool)

ParseClaimConflict inspects a claim error and, when it wraps ErrAlreadyClaimed or ErrNotClaimable, returns the recovered conflict detail and true. For any other error (including nil) it returns the zero ClaimConflict and false.

Parsing keys on the message fragment the engine appends after the sentinel, located with LastIndex so that outer "context: %w" wrapping (which prepends) does not defeat it. Fields are best-effort: an Is-match with an unparseable message still returns true with the corresponding field empty.

type CloseIssueOptions

type CloseIssueOptions = storage.CloseIssueOptions

CloseIssueOptions carries the optional inputs to Storage.CloseIssueChecked — an atomic, guarded close that refuses a still-blocked issue with ErrCloseBlocked unless Force is set. Exported so consumers can name it without importing internal/storage.

type CloseIssueResult

type CloseIssueResult = storage.CloseIssueResult

CloseIssueResult reports the outcome of Storage.CloseIssueChecked. Unchanged is true when the issue was already closed (idempotent no-op).

type Comment

type Comment = types.Comment

Core types from internal/types

type CommentPageCursor

type CommentPageCursor = storage.CommentPageCursor

CommentPageCursor is the resume position for Storage.GetIssueCommentsPage — the (created_at, id) of the last comment already returned, with the zero value starting a walk from the beginning of the thread. Exported so consumers can name it without importing internal/storage.

type CommitInfo

type CommitInfo = storage.CommitInfo

Replication and version control types from internal/storage

type Conflict

type Conflict = storage.Conflict

Replication and version control types from internal/storage

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 DependencyAddOptions

type DependencyAddOptions = storage.DependencyAddOptions

DependencyAddOptions controls transaction-scoped dependency insertion for Transaction.AddDependencyWithOptions. Exported so embedders' bulk graph writers can set SkipCycleCheck per edge and run one whole-graph Transaction.CycleThroughEdges pass before commit (bd-6dnrw.8) instead of paying the recursive per-edge cycle query — which cannot finish inside a per-command budget on molecule-sized graphs (observed: a 67-node/100-edge batch blowing a 120s deadline mid-transaction, gascity 2026-07-17).

Callers that set SkipCycleCheck MUST run Transaction.CycleThroughEdges before commit and fail on new blocks/conditional-blocks/parent-child cycles (waits-for is excluded); skipping the per-edge check trades per-edge cost for one whole-graph check, never graph integrity.

type DependencyCounts

type DependencyCounts = types.DependencyCounts

Core types from internal/types

type DependencyEndpointNotFoundError

type DependencyEndpointNotFoundError = domain.DependencyEndpointNotFoundError

DependencyEndpointNotFoundError is returned by AddDependency when an edge names an endpoint this database can see the absence of; callers errors.As it to read the missing id instead of parsing the message.

type DependencyHierarchyConflictError

type DependencyHierarchyConflictError = domain.DependencyHierarchyConflictError

DependencyHierarchyConflictError is returned by AddDependency when a blocking edge would gate an issue on its own ancestor/descendant (a gate that can never clear).

type DependencyRemoveOptions

type DependencyRemoveOptions = storage.DependencyRemoveOptions

DependencyRemoveOptions controls transaction-scoped dependency removal for Transaction.RemoveDependencyWithOptions. Exported so embedders can request the dependency_removed history event on an explicit edge removal; the plain RemoveDependency default stays silent for structural edge teardown, mirroring the DependencyAddOptions/AddDependencyWithOptions split.

type DependencyType

type DependencyType = types.DependencyType

Core types from internal/types

type DependencyTypeConflictError

type DependencyTypeConflictError = domain.DependencyTypeConflictError

DependencyTypeConflictError is returned by AddDependency when an edge of a different type already exists between the pair; callers errors.As it to read the existing/requested types instead of parsing the message.

type DependentQuerier

type DependentQuerier interface {
	// GetDependentRecords returns raw dependency rows whose target is targetID,
	// paged by the dependency row id (afterID, "" = start). See the engine doc
	// for the two-table span and raw-read/policy-at-hydration contract.
	GetDependentRecords(ctx context.Context, targetID string, depType string, limit int, afterID string) ([]*Dependency, error)
	// GetDependentRecordsForIssues returns raw dependency rows keyed by TARGET id
	// — for a SET of target ids in one batched read, each id's inbound edges (its
	// dependents), across both dependency tables, ALL dep types, de-duped by row
	// id. The batched, target-keyed mirror of GetDependencyRecordsForIssues; same
	// two-table span and raw-read/policy-at-hydration contract as
	// GetDependentRecords, without paging.
	GetDependentRecordsForIssues(ctx context.Context, targetIDs []string) (map[string][]*Dependency, error)
	// CountDependentRecords returns the true total inbound-edge count of targetID
	// (depType "" = all) without paging.
	CountDependentRecords(ctx context.Context, targetID string, depType string) (int, error)
}

DependentQuerier is the target-keyed dependents surface of a Storage: the raw inbound-edge reads that back group-membership. Like EventQuerier it is a NARROW hand-declared root interface (not an alias of DependencyQueryStore), exposing only the calls consumers use. Reach it via AsDependentQuerier.

func AsDependentQuerier

func AsDependentQuerier(s Storage) (DependentQuerier, bool)

AsDependentQuerier returns the DependentQuerier view of s, or (nil, false) when the backing store does not expose the target-keyed dependents reads. Assert once and fail loud. A single direct assertion is sufficient — see the decorator contract on AsIssueClaimer.

type EpicStatus

type EpicStatus = types.EpicStatus

Core types from internal/types

type ErrUnsupported

type ErrUnsupported = storage.ErrUnsupported

ErrUnsupported reports that an operation is unavailable for a storage backend — for example Storage.IssueLifecycle on a backend that cannot serve guarded issue mutations. Exported so consumers can match it with errors.As without importing internal/storage.

type Event

type Event = types.Event

Core types from internal/types

type EventCursor

type EventCursor = storage.EventCursor

EventCursor is a keyset position in the durable events stream, ordered by (created_at, id). The zero value means "from the beginning".

type EventQuerier

type EventQuerier interface {
	// EventsSince returns durable events strictly after cursor, ordered by
	// (created_at ASC, id ASC), bounded by limit (0 = a store default, capped).
	// issueID scopes the feed to one bead's history ("" = all).
	EventsSince(ctx context.Context, cursor EventCursor, issueID string, limit int) ([]*Event, error)
}

EventQuerier is the durable-event-feed surface of a Storage: keyset paging over the durable event log, beyond the base Storage's time-only GetAllEventsSince. It is a NARROW, hand-declared root interface exposing exactly what consumers need — not an alias of the internal EventQueryStore — so the published surface stays small and independent of the engine interface. Reach it via AsEventQuerier.

func AsEventQuerier

func AsEventQuerier(s Storage) (EventQuerier, bool)

AsEventQuerier returns the EventQuerier view of s, or (nil, false) when the backing store does not expose the durable-event feed. Assert once and fail loud. A single direct assertion is sufficient — see the decorator contract on AsIssueClaimer.

type EventType

type EventType = types.EventType

Core types from internal/types

type Issue

type Issue = types.Issue

Core types from internal/types

type IssueClaimer

type IssueClaimer interface {
	// ClaimIssue atomically claims id for actor using compare-and-swap
	// semantics (open ∧ unassigned-or-same-actor). Returns a wrapped
	// ErrAlreadyClaimed or ErrNotClaimable on conflict.
	ClaimIssue(ctx context.Context, id string, actor string) error
	// ClaimReadyIssue atomically claims the first ready issue matching filter,
	// or returns (nil, nil) when none is claimable.
	ClaimReadyIssue(ctx context.Context, filter WorkFilter, actor string) (*Issue, error)
}

IssueClaimer is the atomic-claim surface of a Storage. ClaimIssue and ClaimReadyIssue live on the storage.BulkIssueStore extension rather than the base Storage interface, so callers reach them by type-assertion via AsIssueClaimer rather than off the Storage value directly.

func AsIssueClaimer

func AsIssueClaimer(s Storage) (IssueClaimer, bool)

AsIssueClaimer returns the IssueClaimer view of s when the backing store supports atomic claim (Dolt-backed stores do), and (nil, false) otherwise. Assert once at startup and fail loud.

DECORATOR CONTRACT: a single direct type-assertion is sufficient — no unwrap. ClaimIssue/ClaimReadyIssue (like EventsSince and the dependents reads) live on the engine interface storage.DoltStorage, and the compile-time drift guards below prove storage.DoltStorage satisfies each narrow surface. A store decorator therefore MUST embed storage.DoltStorage — as HookFiringStore does — which promotes these methods so the assertion reaches them THROUGH the decorator. (This is unlike the cmd/bd optional interfaces — StoreLocator, BackupStore, Flattener, … — which are NOT part of DoltStorage, do not promote, and so genuinely need storage.UnwrapStore.) A former storage.UnwrapStore fallback here was provably dead: whenever s satisfies storage.DoltStorage it already satisfies the narrow surface (drift guard), so the direct assertion always wins; and the only decorator, HookFiringStore, forwards by promotion.

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 IssueWithDependencyMetadata

type IssueWithDependencyMetadata = types.IssueWithDependencyMetadata

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 RemoteInfo

type RemoteInfo = storage.RemoteInfo

Replication and version control types from internal/storage

type RemoteStore

type RemoteStore = storage.RemoteStore

RemoteStore provides dolt remote management and replication operations. Use type assertion on a Storage value to access these methods:

if rs, ok := store.(beads.RemoteStore); ok {
    rs.Push(ctx)
}

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 StatusEntry

type StatusEntry = storage.StatusEntry

Replication and version control types from internal/storage

type Storage

type Storage = beads.Storage

Storage is the interface for beads storage operations. Its RunInTransaction callback is invoked at most once per public call; callers retry it explicitly after a callback has started when their operation is safe to repeat.

func Open

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

Open opens a Dolt-backed beads database at the given path. This always opens in embedded mode. Use OpenFromConfig to respect server mode settings from metadata.json.

func OpenBestAvailable

func OpenBestAvailable(ctx context.Context, beadsDir string) (Storage, error)

OpenBestAvailable opens a beads database using the best available backend for the given .beads directory. It reads metadata.json to determine the configured mode:

• Embedded Dolt (default): Opens via the CGo embedded Dolt engine.
• Dolt server: Connects to a dolt sql-server via OpenFromConfig.

The returned Storage must be closed when no longer needed.

beadsDir is the path to the .beads directory.

func OpenFromConfig

func OpenFromConfig(ctx context.Context, beadsDir string) (Storage, error)

OpenFromConfig opens the Dolt implementation using configuration from metadata.json. Unlike Open, this respects Dolt server mode settings and database name configuration. beadsDir is the path to the .beads directory.

func OpenGated

func OpenGated(ctx context.Context, beadsDir string, wait time.Duration) (Storage, error)

OpenGated is OpenFromConfig plus participation in the workspace operation gate: it holds SHARED gates — the workspace gate and the physical database-root gate(s) — for the storage's lifetime (released by Close), so maintenance operations such as mode migration can DETECT this consumer and refuse to run over it, instead of running blind. The gate cannot force a holder out (there is no drain signal); it makes cooperating consumers visible and excludes new ones. Both levels matter: distinct workspaces can share one physical Dolt root, and a workspace-only gate would let maintenance replace that root under a consumer from another workspace. Library consumers that use the ungated Open/OpenFromConfig are invisible to the gate, and gate-aware maintenance operations refuse to proceed on workspaces they cannot prove quiet — prefer OpenGated in long-lived embedders.

The physical roots are the UNION of doltserver.ResolvePhysicalRoots (the side-effect-free CLI-parity resolver: embedded engine's embeddeddolt dir, shared-server dir, proxied-server client info) and doltserver.LibraryOpenRootPath (the root the library open below — which applies central-config defaults and is server-only — will actually use), so the gated directory always includes the one this store opens. A resolver failure is deliberately not fatal here: the same failure will surface from the storage open below with a better error, and the workspace gate alone still covers the workspace-level maintenance conflicts. For a remote server backend there is no local physical root and only the workspace gate is taken.

wait bounds how long to poll for the gates when a maintenance operation holds one exclusively; zero means fail fast. A busy gate is reported as ErrGateBusy (match with errors.Is).

type SyncResult

type SyncResult = storage.SyncResult

Replication and version control types from internal/storage

type SyncStatus

type SyncStatus = storage.SyncStatus

Replication and version control types from internal/storage

type SyncStore

type SyncStore = storage.SyncStore

SyncStore provides high-level sync operations with peers.

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 UpdateIssueOptions

type UpdateIssueOptions = storage.UpdateIssueOptions

UpdateIssueOptions carries the optional inputs to Storage.UpdateIssueChecked — an update with an optional ExpectedVersion compare-and-swap that refuses a concurrently-modified issue with ErrVersionMismatch. Exported so consumers can name it without importing internal/storage.

type VCStatus

type VCStatus = storage.Status

Replication and version control types from internal/storage

type VersionControlReader

type VersionControlReader interface {
	CurrentBranch(ctx context.Context) (string, error)
	ListBranches(ctx context.Context) ([]string, error)
	CommitExists(ctx context.Context, commitHash string) (bool, error)
	GetCurrentCommit(ctx context.Context) (string, error)
	Status(ctx context.Context) (*VCStatus, error)
	Log(ctx context.Context, limit int) ([]CommitInfo, error)
}

VersionControlReader provides read-only version control operations. Write operations (Branch, Checkout, Merge, DeleteBranch) are not yet part of the public API. If you need them, please open an issue.

type WispFilter

type WispFilter = types.WispFilter

Core types from internal/types

type WorkFilter

type WorkFilter = types.WorkFilter

Core types from internal/types