Distributed, git-backed issue tracker with TDD-Wiggum workflow for AI agents.
Beads provides persistent, structured memory for coding agents with built-in TDD-Wiggum workflow — a hybrid approach combining Test-Driven Development with iterative self-correction. It replaces messy markdown plans with a dependency-aware graph, allowing agents to handle long-horizon tasks without losing context while maintaining code quality through automated quality gates.
TDD ensures CORRECTNESS (Make it Work)
Wiggum Loop ensures QUALITY (Make it Right)
Quality Gates ensure STANDARDS (Make it Maintainable)
Human Review ensures CONTROL (Make it Approved)
# Install (macOS/Linux/FreeBSD)
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
# Initialize project
bdai init
# Create a feature with auto-generated spec task
bdai create "User Authentication" --type=feature -p 1
# Creates: bd-abc (feature) + bd-abc-spec (tests)
# Start TDD workflow
bdai pickup bd-abc-spec # Write tests first
bdai pickup bd-abc # Then implement
bdai verify bd-abc # Check quality gates- Git as Database: Issues stored as JSONL in
.beads/. Versioned, branched, and merged like code. - Agent-Optimized: JSON output, dependency tracking, and auto-ready task detection.
- Zero Conflict: Hash-based IDs (
bd-a1b2) prevent merge collisions in multi-agent/multi-branch workflows. - Invisible Infrastructure: SQLite local cache for speed; background daemon for auto-sync.
- Compaction: Semantic "memory decay" summarizes old closed tasks to save context window.
- Test-Driven Development: Automatic spec-task creation ensures tests are written first.
- Wiggum Loop: 10 iterations of focused improvements (edge cases → security → polish).
- Ratchet Effect: Code never degrades — failed changes auto-revert to last good snapshot.
- Quality Gates: Automated checks (coverage ≥80%, lint 0/0, complexity ≤15).
- Human Review: Explicit approval required before closing tasks.
┌─────────────────────────────────────────────────────────────┐
│ TASK LIFECYCLE │
├─────────────────────────────────────────────────────────────┤
│ │
│ Phase 0: SPEC Status: specifying │
│ └─ Write failing tests from PRD │
│ ↓ │
│ Phase 1: IMPLEMENT Status: implementing │
│ └─ Write minimal code to pass tests │
│ └─ Coverage Gate: ≥70% │
│ ↓ │
│ Phase 2: REFINE Status: refining │
│ └─ 10 iterations with Ratchet Effect │
│ └─ Quality Gate: coverage ≥80%, lint 0/0, complexity ≤15 │
│ ↓ │
│ Phase 3: REVIEW Status: needs_review │
│ └─ Human approval required │
│ ↓ │
│ DONE Status: closed │
│ │
└─────────────────────────────────────────────────────────────┘
| Iterations | Focus | What to Improve |
|---|---|---|
| 1-2 | Edge Cases | Boundary conditions, null checks, empty inputs |
| 3-4 | Error Handling | Try/catch, validation, error messages |
| 5-6 | Clarity | Naming, function length, comments |
| 7-8 | Security | OWASP Top 10, injection, auth checks |
| 9 | Performance | O(n) complexity, allocations, caching |
| 10 | Final Polish | Formatting, last review |
The Ratchet Effect guarantees code never degrades:
# On success: snapshot created, iteration advances
$ bdai verify bd-042 --snapshot
> Tests: PASSED, Coverage: 85%
> Created: snapshot-bd-042-iter-5
> Iteration: 6/10
# On failure: auto-revert, retry without incrementing
$ bdai verify bd-042 --snapshot
> Tests: FAILED
> RATCHET: Reverting to snapshot-bd-042-iter-4
> Iteration remains: 5/10| Command | Action |
|---|---|
bdai ready |
List tasks with no open blockers |
bdai create "Title" -p 1 |
Create a P1 task |
bdai show <id> |
View task details and audit trail |
bdai close <id> |
Close a task |
bdai sync |
Sync database with git |
| Command | Action |
|---|---|
bdai pickup <id> |
Start work (sets status to specifying/implementing) |
bdai verify <id> |
Run tests + lint + coverage checks |
bdai verify <id> --snapshot |
Verify + create snapshot + advance iteration |
bdai start-refining <id> |
Move to refining phase (checks coverage gate) |
bdai mark-complete <id> |
Move to needs_review (validates quality gates) |
bdai approve <id> |
Human approval |
| Command | Action |
|---|---|
bdai snapshot <id> |
Create manual snapshot |
bdai revert-to <id> --iteration=N |
Revert to specific iteration |
bdai escalate <id> --reason="..." |
Escalate to human |
bdai challenge-test <id> --test="..." --reason="..." |
Challenge incorrect test |
Before task completion, all gates must pass:
| Gate | Phase 1 | Phase 2+ |
|---|---|---|
| Tests | All pass | All pass |
| Coverage | ≥ 70% | ≥ 80% |
| Lint | — | 0 errors, 0 warnings |
| Complexity | — | ≤ 15 per function |
Beads supports hierarchical IDs for epics:
bd-a3f8(Epic)bd-a3f8.1(Task)bd-a3f8.1.1(Sub-task)
Auto-Spec Creation: Creating a feature/task/bug automatically creates a linked spec-task:
$ bdai create "Auth System" --type=feature
> Created bd-abc: Auth System (feature)
> Created bd-abc-spec: Tests for Auth System (spec)
> Constraint: bd-abc blocked by bd-abc-specUse --no-tests to skip auto-spec creation.
TDD-Wiggum settings in .beads/config.yaml:
tdd_wiggum:
enabled: true
phases:
spec:
auto_create: true
implement:
coverage_gate: 70
refine:
max_iterations: 10
review:
required: true
quality_gates:
coverage:
minimum: 80
lint:
max_errors: 0
max_warnings: 0
complexity:
max_per_function: 15
ratchet:
enabled: true
snapshot_on_success: true
revert_on_failure: true| Method | Command |
|---|---|
| Homebrew | brew install beads |
| npm | npm install -g @beads/bd |
| Go | go install github.com/steveyegge/beads/cmd/bdai@latest |
| Script | curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash |
Requirements: Linux, FreeBSD, macOS, or Windows.
See docs/INSTALLING.md for detailed instructions.
Stealth Mode: Use Beads locally without committing to repo.
bdai init --stealthContributor Mode: Route issues to separate repo (keeps PRs clean).
bdai init --contributorProtected Branches: Commit to separate sync branch.
bdai init --branch beads-syncSee docs/COMMUNITY_TOOLS.md for community-built UIs, extensions, and integrations.
- Installing — Installation guide for all platforms
- Quick Start — Tutorial for new users
- TDD-Wiggum Workflow — Complete TDD + iterative self-correction specification
- Agent Workflow — Detailed agent instructions
- Sync Branch Mode — Working with protected branches
- FAQ — Frequently asked questions
- Troubleshooting — Common issues and solutions
- Articles — Blog posts and tutorials
# 1. Create feature (auto-creates spec task)
bdai create "Password Reset" --type=feature -p 1
# → bd-042: Password Reset (feature)
# → bd-042-spec: Tests for Password Reset (spec)
# 2. Phase 0: SPEC - Write tests
bdai pickup bd-042-spec # Status: specifying
# ... write failing tests ...
bdai close bd-042-spec # Unblocks bd-042
# 3. Phase 1: IMPLEMENT - Make tests pass
bdai pickup bd-042 # Status: implementing
# ... write minimal code ...
bdai verify bd-042 # Check: coverage ≥70%
bdai start-refining bd-042 # Status: refining
# 4. Phase 2: REFINE - Wiggum Loop (10 iterations)
bdai verify bd-042 --snapshot # Iter 1: Edge Cases
bdai verify bd-042 --snapshot # Iter 2: Edge Cases
# ... continue through iterations ...
bdai verify bd-042 --snapshot # Iter 10: Final Polish
# 5. Phase 3: REVIEW - Human approval
bdai mark-complete bd-042 # Status: needs_review
bdai approve bd-042 # Human approves
bdai close bd-042 # Done!
# 6. Sync
bdai sync # Push to remoteMIT License. See LICENSE for details.