Added new section "The Magic: Distributed Database via Git" explaining
the key insight: bd provides the illusion of a centralized database
while actually distributing via git.
Key points:
- Feels like centralized DB (query, update from any machine)
- Actually distributed via git (JSONL source of truth)
- Local SQLite cache for fast queries (<100ms)
- No server, daemon, or configuration needed
- AI-assisted conflict resolution for the rare conflicts
Updated Features section:
- 📦 Git-versioned - JSONL records stored in git
- 🌍 Distributed by design - Multiple machines share one logical DB
Updated comparison table to emphasize no-server advantage:
- "Distributed via git" vs "Git-native storage"
- "No server required" vs "Self-hosted"
This clarifies what makes bd unique: you get database-like behavior
(queries, transactions, dependencies) without database-like operations
(server setup, hosting, network config). Just install bd, clone repo.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Split Quick Start into "For Humans" and "For AI Agents" sections:
- Humans: Just init and add line to CLAUDE.md, then supervise
- Agents: Run quickstart, use --json flags for programmatic workflows
Rewrite "Why bd?" section to clarify the core insight:
- Traditional issue trackers built for humans (web UIs, cards, manual updates)
- bd built for AI agents (JSON APIs, memory, autonomous execution)
- Issues aren't planning artifacts, they're agent memory
- Prevents agents from losing focus during long coding sessions
- Humans supervise rather than micromanage
This reflects the actual design intent: Beads is FOR agents, not just "agent-friendly".
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
This is a fundamental architectural shift from binary SQLite to JSONL as
the source of truth for git workflows.
## New Features
- `bd export --format=jsonl` - Export issues to JSON Lines format
- `bd import` - Import issues from JSONL (create new, update existing)
- `--skip-existing` flag for import to only create new issues
## Architecture Change
**Before:** Binary SQLite database committed to git
**After:** JSONL text files as source of truth, SQLite as ephemeral cache
Benefits:
- Git-friendly text format with clean diffs
- AI-resolvable merge conflicts (append-only is 95% conflict-free)
- Human-readable issue tracking in git
- No binary merge conflicts
## Documentation
- Updated README with JSONL-first workflow and git hooks
- Added TEXT_FORMATS.md analyzing JSONL vs CSV vs binary
- Updated GIT_WORKFLOW.md with historical context
- .gitignore now excludes *.db, includes .beads/*.jsonl
## Implementation Details
- Export sorts issues by ID for consistent diffs
- Import handles both creates and updates atomically
- Proper handling of pointer fields (EstimatedMinutes)
- All tests passing
## Breaking Changes
- Database files (*.db) should now be gitignored
- Use export/import workflow for git collaboration
- Git hooks recommended for automation
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Core features:
- Dependency-aware issue tracking with SQLite backend
- Ready work detection (issues with no open blockers)
- Dependency tree visualization
- Cycle detection and prevention
- Full audit trail
- CLI with colored output
Security and correctness fixes applied:
- Fixed SQL injection vulnerability in UpdateIssue (whitelisted fields)
- Fixed race condition in ID generation (added mutex)
- Fixed cycle detection to return full paths (not just issue IDs)
- Added cycle prevention in AddDependency (validates before commit)
- Added comprehensive input validation (priority, status, types, etc.)
- Fixed N+1 query in GetBlockedIssues (using GROUP_CONCAT)
- Improved query building in GetReadyWork (proper string joining)
- Fixed P0 priority filter bug (using Changed() instead of value check)
All critical and major issues from code review have been addressed.
🤖 Generated with Claude Code
