Skip to content

01-getting-started.md

Latest commit

 

History

History
216 lines (164 loc) · 7.25 KB

01-getting-started.md

File metadata and controls

216 lines (164 loc) · 7.25 KB
layout default
title Chapter 1: Getting Started
nav_order 1
parent Beads Tutorial

Chapter 1: Getting Started

Welcome to Chapter 1: Getting Started. In this part of Beads Tutorial: Git-Backed Task Graph Memory for Coding Agents, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.

This chapter gets Beads installed and initialized in a real project.

Learning Goals

  • install bd via script/package manager
  • initialize a project task graph with bd init
  • verify ready/create/show command loop
  • add minimal AGENTS.md guidance for agent usage

Source References

Summary

You now have a working Beads baseline for structured task tracking.

Next: Chapter 2: Architecture and Data Model

Depth Expansion Playbook

Source Code Walkthrough

.golangci.yml

The fields interface in .golangci.yml handles a key part of this chapter's functionality:

          - gosec
        text: "G115"
      # G117: Exported struct fields matching secret patterns are intentional API fields
      - path: 'internal/compact/compactor\.go|internal/jira/client\.go|internal/linear/types\.go|internal/storage/versioned\.go'
        linters:
          - gosec
        text: "G117"
      # G304: Safe file reads from config paths
      - path: 'internal/config/config\.go'
        linters:
          - gosec
        text: "G304"
      # G306: Config file permissions 0644 are acceptable
      - path: 'internal/config/config\.go'
        linters:
          - gosec
        text: "G306"
      # G703: Path traversal via taint — paths are from config or internal construction
      - linters:
          - gosec
        text: "G703"
      # G704: SSRF via taint in API clients with user-configured URLs
      - path: 'cmd/bd/doctor/(claude|version)\.go|internal/gitlab/client\.go|internal/jira/client\.go|internal/linear/client\.go'
        linters:
          - gosec
        text: "G704"
      # G705: XSS via taint in CLI template rendering (no browser context)
      - path: 'cmd/bd/compact\.go'
        linters:
          - gosec
        text: "G705"
      # errcheck: fmt.Fprintf errors are noise in CLI help text generation

This interface is important because it defines how Beads Tutorial: Git-Backed Task Graph Memory for Coding Agents implements the patterns covered in this chapter.

beads.go

The Open function in beads.go handles a key part of this chapter's functionality:

type Transaction = beads.Transaction

// 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 Open(ctx context.Context, dbPath string) (Storage, error) {
	return dolt.New(ctx, &dolt.Config{Path: dbPath, CreateIfMissing: true})
}

// OpenFromConfig opens a beads database using configuration from metadata.json.
// Unlike Open, this respects Dolt server mode settings and database name
// configuration, connecting to the Dolt SQL server when dolt_mode is "server".
// beadsDir is the path to the .beads directory.
func OpenFromConfig(ctx context.Context, beadsDir string) (Storage, error) {
	return dolt.NewFromConfigWithOptions(ctx, beadsDir, &dolt.Config{CreateIfMissing: true})
}

// FindDatabasePath finds the beads database in the current directory tree
func FindDatabasePath() string {
	return beads.FindDatabasePath()
}

// FindBeadsDir finds the .beads/ directory in the current directory tree.
// Returns empty string if not found.
func FindBeadsDir() string {
	return beads.FindBeadsDir()
}

// DatabaseInfo contains information about a beads database
type DatabaseInfo = beads.DatabaseInfo

// FindAllDatabases finds all beads databases in the system

This function is important because it defines how Beads Tutorial: Git-Backed Task Graph Memory for Coding Agents implements the patterns covered in this chapter.

beads.go

The OpenFromConfig function in beads.go handles a key part of this chapter's functionality:

// 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 Open(ctx context.Context, dbPath string) (Storage, error) {
	return dolt.New(ctx, &dolt.Config{Path: dbPath, CreateIfMissing: true})
}

// OpenFromConfig opens a beads database using configuration from metadata.json.
// Unlike Open, this respects Dolt server mode settings and database name
// configuration, connecting to the Dolt SQL server when dolt_mode is "server".
// beadsDir is the path to the .beads directory.
func OpenFromConfig(ctx context.Context, beadsDir string) (Storage, error) {
	return dolt.NewFromConfigWithOptions(ctx, beadsDir, &dolt.Config{CreateIfMissing: true})
}

// FindDatabasePath finds the beads database in the current directory tree
func FindDatabasePath() string {
	return beads.FindDatabasePath()
}

// FindBeadsDir finds the .beads/ directory in the current directory tree.
// Returns empty string if not found.
func FindBeadsDir() string {
	return beads.FindBeadsDir()
}

// DatabaseInfo contains information about a beads database
type DatabaseInfo = beads.DatabaseInfo

// FindAllDatabases finds all beads databases in the system
func FindAllDatabases() []DatabaseInfo {

This function is important because it defines how Beads Tutorial: Git-Backed Task Graph Memory for Coding Agents implements the patterns covered in this chapter.

beads.go

The FindDatabasePath function in beads.go handles a key part of this chapter's functionality:

}

// FindDatabasePath finds the beads database in the current directory tree
func FindDatabasePath() string {
	return beads.FindDatabasePath()
}

// FindBeadsDir finds the .beads/ directory in the current directory tree.
// Returns empty string if not found.
func FindBeadsDir() string {
	return beads.FindBeadsDir()
}

// DatabaseInfo contains information about a beads database
type DatabaseInfo = beads.DatabaseInfo

// FindAllDatabases finds all beads databases in the system
func FindAllDatabases() []DatabaseInfo {
	return beads.FindAllDatabases()
}

// RedirectInfo contains information about a beads directory redirect
type RedirectInfo = beads.RedirectInfo

// GetRedirectInfo checks if the current beads directory is redirected.
// Returns RedirectInfo with IsRedirected=true if a redirect is active.
func GetRedirectInfo() RedirectInfo {
	return beads.GetRedirectInfo()
}

// Core types from internal/types
type (

This function is important because it defines how Beads Tutorial: Git-Backed Task Graph Memory for Coding Agents implements the patterns covered in this chapter.

How These Components Connect

flowchart TD
    A[fields]
    B[Open]
    C[OpenFromConfig]
    D[FindDatabasePath]
    E[FindBeadsDir]
    A --> B
    B --> C
    C --> D
    D --> E
Loading