Highlight distributed database architecture in README

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>
This commit is contained in:
Steve Yegge
2025-10-12 10:31:56 -07:00
parent 22124d2039
commit a2957f5ee3

View File

@@ -10,6 +10,8 @@ A lightweight, dependency-aware issue tracker designed for AI-supervised coding
- 🔗 **Dependency tracking** - Four dependency types (blocks, related, parent-child, discovered-from)
- 📋 **Ready work detection** - Automatically finds issues with no open blockers
- 🤖 **Agent-friendly** - `--json` flags for programmatic integration
- 📦 **Git-versioned** - JSONL records stored in git, synced across machines
- 🌍 **Distributed by design** - Agents on multiple machines share one logical database via git
- 🏗️ **Extensible** - Add your own tables to the SQLite database
- 🔍 **Project-aware** - Auto-discovers database in `.beads/` directory
- 🌲 **Dependency trees** - Visualize full dependency graphs
@@ -82,6 +84,28 @@ bd update <issue-id> --status in_progress --json
bd close <issue-id> --reason "Implemented" --json
```
## The Magic: Distributed Database via Git
Here's the crazy part: **bd acts like a centralized database, but it's actually distributed via git.**
When you install bd on any machine with your project repo, you get:
- ✅ Full query capabilities (dependencies, ready work, etc.)
- ✅ Fast local operations (<100ms via SQLite)
- ✅ Shared state across all machines (via git)
- ✅ No server, no daemon, no configuration
- ✅ AI-assisted merge conflict resolution
**How it works:**
1. Each machine has a local SQLite cache (`.beads/*.db`) - gitignored
2. Source of truth is JSONL (`.beads/issues.jsonl`) - committed to git
3. `bd export` syncs SQLite → JSONL before commits
4. `bd import` syncs JSONL → SQLite after pulls
5. Git handles distribution; AI handles merge conflicts
**The result:** Agents on your laptop, your desktop, and your coworker's machine all query and update what *feels* like a single shared database, but it's really just git doing what git does best - syncing text files across machines.
No PostgreSQL instance. No MySQL server. No hosted service. Just install bd, clone the repo, and you're connected to the "database."
## Usage
### Creating Issues
@@ -328,11 +352,11 @@ This pattern enables powerful integrations while keeping bd simple and focused.
| Dependency tracking | ✅ | ⚠️ | ✅ | ✅ |
| Ready work detection | ✅ | ❌ | ❌ | ❌ |
| Agent-friendly (JSON) | ✅ | ⚠️ | ⚠️ | ⚠️ |
| Git-native storage | ✅ (JSONL) | ❌ | ❌ | ❌ |
| Distributed via git | ✅ | ❌ | ❌ | ❌ |
| Works offline | ✅ | ❌ | ❌ | ❌ |
| AI-resolvable conflicts | ✅ | ❌ | ❌ | ❌ |
| Extensible database | ✅ | ❌ | ❌ | ❌ |
| Offline first | ✅ | ❌ | ❌ | ❌ |
| Self-hosted | ✅ | ⚠️ | ⚠️ | ❌ |
| No server required | ✅ | ❌ | ❌ | ❌ |
## Why bd?