Consolidate test execution and design guidance around the smallest trustworthy seam, narrow doubles, semantic versus persistence conformance, strict E2E admission, and proportional verification. Convert the former philosophy documents to compatibility pointers. Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of CI Bot Co-authored-by: CI Bot <ci@beads.test>
3.5 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
-
Database Runtime Layer
- Embedded mode runs Dolt in-process through
internal/storage/embeddeddolt/ - Server mode uses
internal/doltserver/andinternal/storage/db/ - Proxy and pidfile helpers live under
internal/storage/db/ - Storage-facing server adapters live under
internal/storage/doltserver/
- Embedded mode runs Dolt in-process through
-
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 via
bd dolt push/bd dolt pull - Hash-based IDs: Automatic collision prevention (v0.20+)
Core implementation:
- Dolt storage:
internal/storage/dolt/ - Embedded runtime:
internal/storage/embeddeddolt/ - Server runtime:
internal/doltserver/,internal/storage/db/, andinternal/storage/doltserver/ - Sync commands:
cmd/bd/dolt_*.go,cmd/bd/sync_*.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
Development Command Source
Use the canonical TESTING.md for test commands, test design, and PR-readiness gates. This file should not duplicate command matrices or version-management workflows.
Do NOT use
go build -o bdorgo installdirectly — they create stale binaries that shadow~/.local/bin/bd. Always usemake install.
Testing
Testing guidance lives in TESTING.md. Architecture-specific notes for Claude are limited to where tests touch agent setup, hooks, or instruction-file generation.
Important Notes
- Always read AGENTS.md first - it has the complete workflow
- 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)
- docs/core-concepts/labels.md - Complete label system guide
- docs/reference/configuration.md - Configuration system
When Adding Features
See AGENTS.md "Adding a New Command" and "Adding Storage Features" sections for step-by-step guidance.