Fix stale agent-facing documentation for Dolt-only storage, build/test commands, claiming work, and removed references. Includes maintainer cleanup to align remaining stale test guidance with the current make test / test-icu-path policy.\n\nCo-authored-by: Kevin Glynn <12972584+kevglynn@users.noreply.github.com>\nCo-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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
-
Storage Layer (
internal/storage/)- Dolt in
storage/dolt/— version-controlled SQL database with cell-level merge - Common types and interfaces in
storage.go
- Dolt in
-
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
-
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
--jsonfor programmatic use - Main entry point in
main.go
- Cobra-based commands (one file per command:
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 exportavailable for data portability,bd init --from-jsonlfor 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 systemComment: Threaded discussionsEvent: Full audit trail
Common Development Commands
# Build and install bd to ~/.local/bin (canonical location)
make install
# Test
make test
go test -tags gms_pure_go -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 bdorgo installdirectly — they create stale binaries that shadow~/.local/bin/bd. Always usemake 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(seescripttest_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 pullfor remote sync - Check for duplicates proactively:
bd duplicates --auto-merge - Use
--jsonflags 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)
- 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.