beads/docs/CLAUDE.md
garnet 3dae6bb3df refactor: remove gastown/Gas Town string references from beads code and docs (bd-1ue8)
Replace gastown-specific references with generic alternatives throughout
the codebase:

- Rename --gastown flag to --orchestrator in bd doctor
- Rename gastownMode/gastownThreshold params to orchestratorMode/orchestratorThreshold
- Rename isGasTownTownRoot() to isOrchestratorRoot()
- Replace "gastown" in CLI examples with generic rig names (my-project, other-project)
- Update comments replacing "Gas Town" with "orchestrator" or "multi-agent workspace"
- Update active docs (DOLT.md, CONFIG.md, ADVANCED.md, etc.)
- Update test data to use generic names instead of "gastown"
- Update role templates (deacon, witness, refinery) to use generic language

Preserved as historical (not changed):
- CHANGELOG.md entries (historical record)
- ARTICLES.md (links to real published articles)
- info.go version notes (historical release notes)
- gastown/ file path references in dolt-concurrency.md (point to actual repo)
2026-03-20 18:39:50 -07:00

3.8 KiB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

beads (command: bd) is a Dolt-powered issue tracker for AI-supervised coding workflows. Git integration is optional — see BEADS_DIR + --stealth for git-free operation. We dogfood our own tool.

IMPORTANT: See AGENTS.md for complete workflow instructions, bd commands, and development guidelines.

Architecture Overview

Three-Layer Design

  1. Storage Layer (internal/storage/)

    • Dolt in storage/dolt/ — version-controlled SQL database with cell-level merge
    • Common types and interfaces in storage.go
  2. RPC Layer (internal/rpc/)

    • Client/server architecture using Unix domain sockets (Windows named pipes)
    • Protocol defined in protocol.go
    • Server split into focused files: server_core.go, server_issues_epics.go, server_labels_deps_comments.go, etc.
    • Used by Dolt server mode for multi-writer access
  3. CLI Layer (cmd/bd/)

    • Cobra-based commands (one file per command: create.go, list.go, etc.)
    • Direct database access (embedded mode for standalone, server mode for orchestrator)
    • All commands support --json for programmatic use
    • Main entry point in main.go

Storage Architecture

Beads uses Dolt as its storage backend — a version-controlled SQL database:

Dolt DB (.beads/dolt/)
    ↕ Dolt commits (automatic per write)
    ↕ Dolt push/pull (native sync)
Remote (Dolt remotes: DoltHub, S3, GCS, etc.)
  • Write path: CLI → Dolt → auto-commit to Dolt history
  • Read path: Direct SQL queries against Dolt
  • Sync: Dolt handles versioning and sync natively; bd export available for data portability, bd init --from-jsonl for bootstrapping
  • Hash-based IDs: Automatic collision prevention (v0.20+)

Core implementation:

  • Dolt storage: internal/storage/dolt/
  • Export: cmd/bd/export.go
  • Sync: cmd/bd/sync_git.go

Key Data Types

See internal/types/types.go:

  • Issue: Core work item (title, description, status, priority, etc.)
  • Dependency: Four types (blocks, related, parent-child, discovered-from)
  • Label: Flexible tagging system
  • Comment: Threaded discussions
  • Event: Full audit trail

Common Development Commands

# Build and install bd to ~/.local/bin (canonical location)
make install

# Test
go test ./...
go test -coverprofile=coverage.out ./...

# Run linter (baseline warnings documented in docs/LINTING.md)
golangci-lint run ./...

# Version management
./scripts/bump-version.sh 0.9.3 --commit

# Verify installed binary
bd init --prefix test
bd create "Test issue" -p 1
bd ready

Do NOT use go build -o bd or go install directly — they create stale binaries that shadow ~/.local/bin/bd. Always use make install.

Testing Philosophy

  • Unit tests live next to implementation (*_test.go)
  • Integration tests use real Dolt databases (via server in temp dirs)
  • Script-based tests in cmd/bd/testdata/*.txt (see scripttest_test.go)
  • RPC layer has extensive isolation and edge case coverage

Important Notes

  • Always read AGENTS.md first - it has the complete workflow
  • Install git hooks: bd hooks install
  • Use bd dolt push / bd dolt pull for remote sync
  • Check for duplicates proactively: bd duplicates --auto-merge
  • Use --json flags for all programmatic use

Key Files

  • AGENTS.md - Complete workflow and development guide (READ THIS!)
  • README.md - User-facing documentation
  • ADVANCED.md - Advanced features (rename, merge, compaction)
  • EXTENDING.md - How to add custom tables to the database
  • LABELS.md - Complete label system guide
  • CONFIG.md - Configuration system

When Adding Features

See AGENTS.md "Adding a New Command" and "Adding Storage Features" sections for step-by-step guidance.