beads/docs/CLAUDE.md

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 git-backed issue tracker for AI-supervised coding workflows. 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/)

   • Interface-based design in storage.go
   • SQLite implementation in storage/sqlite/
   • Memory backend in storage/memory/ for testing
   • Extensions can add custom tables via UnderlyingDB() (see EXTENDING.md)

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.
   • Per-workspace daemons communicate via .beads/bd.sock

3. CLI Layer (cmd/bd/)

   • Cobra-based commands (one file per command: create.go, list.go, etc.)
   • Commands try daemon RPC first, fall back to direct database access
   • All commands support --json for programmatic use
   • Main entry point in main.go

Distributed Database Pattern

The "magic" is in the auto-sync between SQLite and JSONL:

SQLite DB (.beads/beads.db, gitignored)
    ↕ auto-sync (5s debounce)
JSONL (.beads/issues.jsonl, git-tracked)
    ↕ git push/pull
Remote JSONL (shared across machines)

• Write path: CLI → SQLite → JSONL export → git commit
• Read path: git pull → JSONL import → SQLite → CLI
• Hash-based IDs: Automatic collision prevention (v0.20+)

Core implementation:

• Export: cmd/bd/export.go, cmd/bd/autoflush.go
• Import: cmd/bd/import.go, cmd/bd/autoimport.go
• Collision detection: internal/importer/importer.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

Daemon Architecture

Each workspace gets its own daemon process:

• Auto-starts on first command (unless disabled)
• Handles auto-sync, batching, and background operations
• Socket at .beads/bd.sock (or .beads/bd.pipe on Windows)
• Version checking prevents mismatches after upgrades
• Manage with bd daemons command (see AGENTS.md)

Common Development Commands

# Build and test
go build -o bd ./cmd/bd
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

# Local testing
./bd init --prefix test
./bd create "Test issue" -p 1
./bd ready

Testing Philosophy

• Unit tests live next to implementation (*_test.go)
• Integration tests use real SQLite databases (:memory: or temp files)
• 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
• Use bd --no-daemon in git worktrees (see AGENTS.md for why)
• Install git hooks for zero-lag sync: ./examples/git-hooks/install.sh
• Run bd sync at end of agent sessions to force immediate flush/commit/push
• 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.