johno/beads
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refactor documentation: condense README and create specialized docs

Browse Source 
- Reduce README from 1000 to ~400 lines, focusing on core features
- Create INSTALLING.md with all installation methods and platform details
- Create ADVANCED.md with prefix renaming, merging, global daemon, worktrees
- Create TROUBLESHOOTING.md with all common issues and solutions
- Create FAQ.md with frequently asked questions
- Add cross-links between all documentation files
- Improve discoverability with organized topic-specific guides

Amp-Thread-ID: https://ampcode.com/threads/T-8e2b3099-beb9-492a-9781-0e3da9fa9ba8
Co-authored-by: Amp <amp@ampcode.com>
This commit is contained in:
Steve Yegge
2025-10-23 17:03:27 -07:00
parent ac7d8c683a
commit 2455a856e1
5 changed files with 1533 additions and 1555 deletions
Download Patch File Download Diff File Expand all files Collapse all files

425
ADVANCED.md Normal file
View File

@@ -0,0 +1,425 @@
# Advanced bd Features
This guide covers advanced features for power users and specific use cases.
## Table of Contents
- [Renaming Prefix](#renaming-prefix)
- [Merging Duplicate Issues](#merging-duplicate-issues)
- [Global Daemon for Multiple Projects](#global-daemon-for-multiple-projects)
- [Multi-Repository Commands](#multi-repository-commands)
- [Git Worktrees](#git-worktrees)
- [Handling Import Collisions](#handling-import-collisions)
- [Custom Git Hooks](#custom-git-hooks)
- [Extensible Database](#extensible-database)
## Renaming Prefix
Change the issue prefix for all issues in your database. This is useful if your prefix is too long or you want to standardize naming.
```bash
# Preview changes without applying
bd rename-prefix kw- --dry-run
# Rename from current prefix to new prefix
bd rename-prefix kw-
# JSON output
bd rename-prefix kw- --json
```
The rename operation:
- Updates all issue IDs (e.g., `knowledge-work-1` → `kw-1`)
- Updates all text references in titles, descriptions, design notes, etc.
- Updates dependencies and labels
- Updates the counter table and config
**Prefix validation rules:**
- Max length: 8 characters
- Allowed characters: lowercase letters, numbers, hyphens
- Must start with a letter
- Must end with a hyphen (or will be trimmed to add one)
- Cannot be empty or just a hyphen
Example workflow:
```bash
# You have issues like knowledge-work-1, knowledge-work-2, etc.
bd list # Shows knowledge-work-* issues
# Preview the rename
bd rename-prefix kw- --dry-run
# Apply the rename
bd rename-prefix kw-
# Now you have kw-1, kw-2, etc.
bd list # Shows kw-* issues
```
## Merging Duplicate Issues
Consolidate duplicate issues into a single issue while preserving dependencies and references:
```bash
# Merge bd-42 and bd-43 into bd-41
bd merge bd-42 bd-43 --into bd-41
# Merge multiple duplicates at once
bd merge bd-10 bd-11 bd-12 --into bd-10
# Preview merge without making changes
bd merge bd-42 bd-43 --into bd-41 --dry-run
# JSON output
bd merge bd-42 bd-43 --into bd-41 --json
```
**What the merge command does:**
1. **Validates** all issues exist and prevents self-merge
2. **Closes** source issues with reason `Merged into bd-X`
3. **Migrates** all dependencies from source issues to target
4. **Updates** text references across all issue descriptions, notes, design, and acceptance criteria
**Example workflow:**
```bash
# You discover bd-42 and bd-43 are duplicates of bd-41
bd show bd-41 bd-42 bd-43
# Preview the merge
bd merge bd-42 bd-43 --into bd-41 --dry-run
# Execute the merge
bd merge bd-42 bd-43 --into bd-41
# ✓ Merged 2 issue(s) into bd-41
# Verify the result
bd show bd-41 # Now has dependencies from bd-42 and bd-43
bd dep tree bd-41 # Shows unified dependency tree
```
**Important notes:**
- Source issues are permanently closed (status: `closed`)
- All dependencies pointing to source issues are redirected to target
- Text references like "see bd-42" are automatically rewritten to "see bd-41"
- Operation cannot be undone (but git history preserves the original state)
- Not yet supported in daemon mode (use `--no-daemon` flag)
**AI Agent Workflow:**
When agents discover duplicate issues, they should:
1. Search for similar issues: `bd list --json | grep "similar text"`
2. Compare issue details: `bd show bd-41 bd-42 --json`
3. Merge duplicates: `bd merge bd-42 --into bd-41`
4. File a discovered-from issue if needed: `bd create "Found duplicates during bd-X" --deps discovered-from:bd-X`
## Global Daemon for Multiple Projects
**New in v0.9.11:** Use a single daemon process to serve all projects on your machine.
### Starting the Global Daemon
```bash
# Start global daemon (one per machine)
bd daemon --global
# Verify it's running
ps aux | grep "bd daemon"
# Stop it
pkill -f "bd daemon --global"
```
### Benefits
- **Single process** serves all bd databases on your machine
- **Automatic workspace detection** - no configuration needed
- **Persistent background service** - survives terminal restarts
- **Lower memory footprint** than per-project daemons
### How It Works
```bash
# In any project directory
cd ~/projects/webapp && bd ready # Uses global daemon
cd ~/projects/api && bd ready # Uses global daemon
```
The global daemon:
1. Checks for local daemon socket (`.beads/bd.sock`) in your current workspace
2. Routes requests to the correct database based on your current working directory
3. Auto-starts the local daemon if it's not running (with exponential backoff on failures)
4. Each project gets its own isolated daemon serving only its database
**Note:** Global daemon doesn't require git repos, making it suitable for non-git projects or multi-repo setups.
## Multi-Repository Commands
**New in v0.9.12:** When using a global daemon, use `bd repos` to view and manage work across all cached repositories.
```bash
# List all cached repositories
bd repos list
# View ready work across all repos
bd repos ready
# Group ready work by repository
bd repos ready --group
# Filter by priority
bd repos ready --priority 1
# Filter by assignee
bd repos ready --assignee alice
# View combined statistics
bd repos stats
# Clear repository cache (free resources)
bd repos clear-cache
```
**Example output:**
```bash
$ bd repos list
📁 Cached Repositories (3):
/Users/alice/projects/webapp
Prefix: webapp-
Issue Count: 45
Status: active
/Users/alice/projects/api
Prefix: api-
Issue Count: 12
Status: active
/Users/alice/projects/docs
Prefix: docs-
Issue Count: 8
Status: active
$ bd repos ready --group
📋 Ready work across 3 repositories:
/Users/alice/projects/webapp (4 issues):
1. [P1] webapp-23: Fix navigation bug
Estimate: 30 min
2. [P2] webapp-45: Add loading spinner
Estimate: 15 min
...
/Users/alice/projects/api (2 issues):
1. [P0] api-10: Fix critical auth bug
Estimate: 60 min
2. [P1] api-12: Add rate limiting
Estimate: 45 min
$ bd repos stats
📊 Combined Statistics Across All Repositories:
Total Issues: 65
Open: 23
In Progress: 5
Closed: 37
Blocked: 3
Ready: 15
📁 Per-Repository Breakdown:
/Users/alice/projects/webapp:
Total: 45 Ready: 10 Blocked: 2
/Users/alice/projects/api:
Total: 12 Ready: 3 Blocked: 1
/Users/alice/projects/docs:
Total: 8 Ready: 2 Blocked: 0
```
**Requirements:**
- Global daemon must be running (`bd daemon --global`)
- At least one command has been run in each repository (to cache it)
- `--json` flag available for programmatic use
**Use cases:**
- Get an overview of all active projects
- Find highest-priority work across all repos
- Balance workload across multiple projects
- Track overall progress and statistics
- Identify which repos need attention
## Git Worktrees
**⚠️ Important Limitation:** Daemon mode does not work correctly with `git worktree`.
**The Problem:**
Git worktrees share the same `.git` directory and thus share the same `.beads` database. The daemon doesn't know which branch each worktree has checked out, which can cause it to commit/push to the wrong branch.
**What you lose without daemon mode:**
- **Auto-sync** - No automatic commit/push of changes (use `bd sync` manually)
- **MCP server** - The beads-mcp server requires daemon mode for multi-repo support
- **Background watching** - No automatic detection of remote changes
**Solutions for Worktree Users:**
1. **Use `--no-daemon` flag** (recommended):
```bash
bd --no-daemon ready
bd --no-daemon create "Fix bug" -p 1
bd --no-daemon update bd-42 --status in_progress
```
2. **Disable daemon via environment variable** (for entire worktree session):
```bash
export BEADS_NO_DAEMON=1
bd ready # All commands use direct mode
```
3. **Disable auto-start** (less safe, still warns):
```bash
export BEADS_AUTO_START_DAEMON=false
```
**Automatic Detection:**
bd automatically detects when you're in a worktree and shows a prominent warning if daemon mode is active. The `--no-daemon` mode works correctly with worktrees since it operates directly on the database without shared state.
**Why It Matters:**
The daemon maintains its own view of the current working directory and git state. When multiple worktrees share the same `.beads` database, the daemon may commit changes intended for one branch to a different branch, leading to confusion and incorrect git history.
## Handling Import Collisions
When merging branches or pulling changes, you may encounter ID collisions (same ID, different content). bd detects and safely handles these:
**Check for collisions after merge:**
```bash
# After git merge or pull
bd import -i .beads/issues.jsonl --dry-run
# Output shows:
# === Collision Detection Report ===
# Exact matches (idempotent): 15
# New issues: 5
# COLLISIONS DETECTED: 3
#
# Colliding issues:
# bd-10: Fix authentication (conflicting fields: [title, priority])
# bd-12: Add feature (conflicting fields: [description, status])
```
**Resolve collisions automatically:**
```bash
# Let bd resolve collisions by remapping incoming issues to new IDs
bd import -i .beads/issues.jsonl --resolve-collisions
# bd will:
# - Keep existing issues unchanged
# - Assign new IDs to colliding issues (bd-25, bd-26, etc.)
# - Update ALL text references and dependencies automatically
# - Report the remapping with reference counts
```
**Important**: The `--resolve-collisions` flag is safe and recommended for branch merges. It preserves the existing database and only renumbers the incoming colliding issues. All text mentions like "see bd-10" and dependency links are automatically updated to use the new IDs.
**Manual resolution** (alternative):
If you prefer manual control, resolve the Git conflict in `.beads/issues.jsonl` directly, then import normally without `--resolve-collisions`.
### Advanced: Intelligent Merge Tools
For Git merge conflicts in `.beads/issues.jsonl`, consider using **[beads-merge](https://github.com/neongreen/mono/tree/main/beads-merge)** - a specialized merge tool by @neongreen that:
- Matches issues across conflicted JSONL files
- Merges fields intelligently (e.g., combines labels, picks newer timestamps)
- Resolves conflicts automatically where possible
- Leaves remaining conflicts for manual resolution
- Works as a Git/jujutsu merge driver
**Two types of conflicts, two tools:**
- **Git merge conflicts** (same issue modified in two branches) → Use beads-merge during git merge
- **ID collisions** (different issues with same ID) → Use `bd import --resolve-collisions` after merge
## Custom Git Hooks
For immediate export (no 5-second wait) and guaranteed import after git operations, install the git hooks:
### Using the Installer
```bash
cd examples/git-hooks
./install.sh
```
### Manual Setup
Create `.git/hooks/pre-commit`:
```bash
#!/bin/bash
bd export -o .beads/issues.jsonl
git add .beads/issues.jsonl
```
Create `.git/hooks/post-merge`:
```bash
#!/bin/bash
bd import -i .beads/issues.jsonl
```
Create `.git/hooks/post-checkout`:
```bash
#!/bin/bash
bd import -i .beads/issues.jsonl
```
Make hooks executable:
```bash
chmod +x .git/hooks/pre-commit .git/hooks/post-merge .git/hooks/post-checkout
```
**Note:** Auto-sync is already enabled by default, so git hooks are optional. They're useful if you need immediate export or guaranteed import after git operations.
## Extensible Database
bd uses SQLite, which you can extend with your own tables and queries. This allows you to:
- Add custom metadata to issues
- Build integrations with other tools
- Implement custom workflows
- Create reports and analytics
**See [EXTENDING.md](EXTENDING.md) for complete documentation:**
- Database schema and structure
- Adding custom tables
- Joining with issue data
- Example integrations
- Best practices
**Example use case:**
```sql
-- Add time tracking table
CREATE TABLE time_entries (
id INTEGER PRIMARY KEY,
issue_id TEXT NOT NULL,
duration_minutes INTEGER NOT NULL,
recorded_at DATETIME DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY(issue_id) REFERENCES issues(id)
);
-- Query total time per issue
SELECT i.id, i.title, SUM(t.duration_minutes) as total_minutes
FROM issues i
LEFT JOIN time_entries t ON i.id = t.issue_id
GROUP BY i.id;
```
## Next Steps
- **[README.md](README.md)** - Core features and quick start
- **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** - Common issues and solutions
- **[FAQ.md](FAQ.md)** - Frequently asked questions
- **[CONFIG.md](CONFIG.md)** - Configuration system guide
- **[EXTENDING.md](EXTENDING.md)** - Database extension patterns

340
FAQ.md Normal file
View File

@@ -0,0 +1,340 @@
# Frequently Asked Questions
Common questions about bd (beads) and how to use it effectively.
## General Questions
### What is bd?
bd is a lightweight, git-based issue tracker designed for AI coding agents. It provides dependency-aware task management with automatic sync across machines via git.
### Why not just use GitHub Issues?
GitHub Issues + gh CLI can approximate some features, but fundamentally cannot replicate what AI agents need:
**Key Differentiators:**
1. **Typed Dependencies with Semantics**
- bd: Four types (`blocks`, `related`, `parent-child`, `discovered-from`) with different behaviors
- GH: Only "blocks/blocked by" links, no semantic enforcement, no `discovered-from` for agent work discovery
2. **Deterministic Ready-Work Detection**
- bd: `bd ready` computes transitive blocking offline in ~10ms, no network required
- GH: No built-in "ready" concept; would require custom GraphQL + sync service + ongoing maintenance
3. **Git-First, Offline, Branch-Scoped Task Memory**
- bd: Works offline, issues live on branches, mergeable with code via `bd import --resolve-collisions`
- GH: Cloud-first, requires network/auth, global per-repo, no branch-scoped task state
4. **AI-Resolvable Conflicts & Duplicate Merge**
- bd: Automatic collision resolution, duplicate merge with dependency consolidation and reference rewriting
- GH: Manual close-as-duplicate, no safe bulk merge, no cross-reference updates
5. **Extensible Local Database**
- bd: Add SQL tables and join with issue data locally (see [EXTENDING.md](EXTENDING.md))
- GH: No local database; would need to mirror data externally
6. **Agent-Native APIs**
- bd: Consistent `--json` on all commands, dedicated MCP server with auto workspace detection
- GH: Mixed JSON/text output, GraphQL requires custom queries, no agent-focused MCP layer
**When to use each:** GitHub Issues excels for human teams in web UI with cross-repo dashboards and integrations. bd excels for AI agents needing offline, git-synchronized task memory with graph semantics and deterministic queries.
See [GitHub issue #125](https://github.com/steveyegge/beads/issues/125) for detailed comparison.
### How is this different from Taskwarrior?
Taskwarrior is excellent for personal task management, but bd is built for AI agents:
- **Explicit agent semantics**: `discovered-from` dependency type, `bd ready` for queue management
- **JSON-first design**: Every command has `--json` output
- **Git-native sync**: No sync server setup required
- **Merge-friendly JSONL**: One issue per line, AI-resolvable conflicts
- **Extensible SQLite**: Add your own tables without forking
### Can I use bd without AI agents?
Absolutely! bd is a great CLI issue tracker for humans too. The `bd ready` command is useful for anyone managing dependencies. Think of it as "Taskwarrior meets git."
### Is this production-ready?
**Current status: Alpha (v0.9.11)**
bd is in active development and being dogfooded on real projects. The core functionality (create, update, dependencies, ready work, collision resolution) is stable and well-tested. However:
- ⚠️ **Alpha software** - No 1.0 release yet
- ⚠️ **API may change** - Command flags and JSONL format may evolve before 1.0
- ✅ **Safe for development** - Use for development/internal projects
- ✅ **Data is portable** - JSONL format is human-readable and easy to migrate
- 📈 **Rapid iteration** - Expect frequent updates and improvements
**When to use bd:**
- ✅ AI-assisted development workflows
- ✅ Internal team projects
- ✅ Personal productivity with dependency tracking
- ✅ Experimenting with agent-first tools
**When to wait:**
- ❌ Mission-critical production systems (wait for 1.0)
- ❌ Large enterprise deployments (wait for stability guarantees)
- ❌ Long-term archival (though JSONL makes migration easy)
Follow the repo for updates and the path to 1.0!
## Usage Questions
### Do I need to run export/import manually?
**No! Sync is automatic by default.**
bd automatically:
- **Exports** to JSONL after CRUD operations (5-second debounce)
- **Imports** from JSONL when it's newer than DB (after `git pull`)
**Optional**: For immediate export (no 5-second wait) and guaranteed import after git operations, install the git hooks:
```bash
cd examples/git-hooks && ./install.sh
```
**Disable auto-sync** if needed:
```bash
bd --no-auto-flush create "Issue" # Disable auto-export
bd --no-auto-import list # Disable auto-import
```
### Can I track issues for multiple projects?
**Yes! Each project is completely isolated.** bd uses project-local databases:
```bash
cd ~/project1 && bd init --prefix proj1
cd ~/project2 && bd init --prefix proj2
```
Each project gets its own `.beads/` directory with its own database and JSONL file. bd auto-discovers the correct database based on your current directory (walks up like git).
**Multi-project scenarios work seamlessly:**
- Multiple agents working on different projects simultaneously → No conflicts
- Same machine, different repos → Each finds its own `.beads/*.db` automatically
- Agents in subdirectories → bd walks up to find the project root (like git)
- **Global daemon** → One daemon process serves all projects (v0.9.11+)
**Limitation:** Issues cannot reference issues in other projects. Each database is isolated by design. If you need cross-project tracking, initialize bd in a parent directory that contains both projects.
**Example:** Multiple agents, multiple projects, same machine:
```bash
# Agent 1 working on web app
cd ~/work/webapp && bd ready --json # Uses ~/work/webapp/.beads/webapp.db
# Agent 2 working on API
cd ~/work/api && bd ready --json # Uses ~/work/api/.beads/api.db
# No conflicts! Completely isolated databases.
```
**Recommended for multi-project setups:** Use the global daemon (`bd daemon --global`) to serve all projects with a single daemon process. See [ADVANCED.md#global-daemon-for-multiple-projects](ADVANCED.md#global-daemon-for-multiple-projects).
### What happens if two agents work on the same issue?
The last agent to export/commit wins. This is the same as any git-based workflow. To prevent conflicts:
- Have agents claim work with `bd update <id> --status in_progress`
- Query by assignee: `bd ready --assignee agent-name`
- Review git diffs before merging
For true multi-agent coordination, you'd need additional tooling (like locks or a coordination server). bd handles the simpler case: multiple humans/agents working on different tasks, syncing via git.
### Why JSONL instead of JSON?
- ✅ **Git-friendly**: One line per issue = clean diffs
- ✅ **Mergeable**: Concurrent appends rarely conflict
- ✅ **Human-readable**: Easy to review changes
- ✅ **Scriptable**: Use `jq`, `grep`, or any text tools
- ✅ **Portable**: Export/import between databases
See [TEXT_FORMATS.md](TEXT_FORMATS.md) for detailed analysis.
### How do I handle merge conflicts?
When two developers create new issues:
```diff
{"id":"bd-1","title":"First issue",...}
{"id":"bd-2","title":"Second issue",...}
+{"id":"bd-3","title":"From branch A",...}
+{"id":"bd-4","title":"From branch B",...}
```
Git may show a conflict, but resolution is simple: **keep both lines** (both changes are compatible).
For ID collisions (same ID, different content):
```bash
bd import -i .beads/issues.jsonl --resolve-collisions
```
See [ADVANCED.md#handling-import-collisions](ADVANCED.md#handling-import-collisions) for details.
## Migration Questions
### How do I migrate from GitHub Issues / Jira / Linear?
We don't have automated migration tools yet, but you can:
1. Export issues from your current tracker (usually CSV or JSON)
2. Write a simple script to convert to bd's JSONL format
3. Import with `bd import -i issues.jsonl`
See [examples/](examples/) for scripting patterns. Contributions welcome!
### Can I export back to GitHub Issues / Jira?
Not yet built-in, but you can:
1. Export from bd: `bd export -o issues.jsonl --json`
2. Write a script to convert JSONL to your target format
3. Use the target system's API to import
The [CONFIG.md](CONFIG.md) guide shows how to store integration settings. Contributions for standard exporters welcome!
## Performance Questions
### How does bd handle scale?
bd uses SQLite, which handles millions of rows efficiently. For a typical project with thousands of issues:
- Commands complete in <100ms
- Full-text search is instant
- Dependency graphs traverse quickly
- JSONL files stay small (one line per issue)
For extremely large projects (100k+ issues), you might want to filter exports or use multiple databases per component.
### What if my JSONL file gets too large?
Use compaction to remove old closed issues:
```bash
# Preview what would be compacted
bd compact --dry-run --all
# Compact issues closed more than 90 days ago
bd compact --days 90
```
Or split your project into multiple databases:
```bash
cd ~/project/frontend && bd init --prefix fe
cd ~/project/backend && bd init --prefix be
```
## Use Case Questions
### Can I use bd for non-code projects?
Sure! bd is just an issue tracker. Use it for:
- Writing projects (chapters as issues, dependencies as outlines)
- Research projects (papers, experiments, dependencies)
- Home projects (renovations with blocking tasks)
- Any workflow with dependencies
The agent-friendly design works for any AI-assisted workflow.
### Can I use bd with multiple AI agents simultaneously?
Yes! Each agent can:
1. Query ready work: `bd ready --assignee agent-name`
2. Claim issues: `bd update <id> --status in_progress --assignee agent-name`
3. Create discovered work: `bd create "Found issue" --deps discovered-from:<parent-id>`
4. Sync via git commits
bd's git-based sync means agents work independently and merge their changes like developers do.
### Does bd work offline?
Yes! bd is designed for offline-first operation:
- All queries run against local SQLite database
- No network required for any commands
- Sync happens via git push/pull when you're online
- Full functionality available without internet
This makes bd ideal for:
- Working on planes/trains
- Unstable network connections
- Air-gapped environments
- Privacy-sensitive projects
## Technical Questions
### What dependencies does bd have?
bd is a single static binary with no runtime dependencies:
- **Language**: Go 1.24+
- **Database**: SQLite (embedded, pure Go driver)
- **Optional**: Git (for sync across machines)
That's it! No PostgreSQL, no Redis, no Docker, no node_modules.
### Can I extend bd's database?
Yes! See [EXTENDING.md](EXTENDING.md) for how to:
- Add custom tables to the SQLite database
- Join with issue data
- Build custom queries
- Create integrations
### Does bd support Windows?
Yes! bd has native Windows support (v0.9.0+):
- No MSYS or MinGW required
- PowerShell install script
- Works with Windows paths and filesystem
- Daemon uses TCP instead of Unix sockets
See [INSTALLING.md](INSTALLING.md#windows-11) for details.
### Can I use bd with git worktrees?
Yes, but with limitations. The daemon doesn't work correctly with worktrees, so use `--no-daemon` mode:
```bash
export BEADS_NO_DAEMON=1
bd ready
bd create "Fix bug" -p 1
```
See [ADVANCED.md#git-worktrees](ADVANCED.md#git-worktrees) for details.
## Getting Help
### Where can I get more help?
- **Documentation**: [README.md](README.md), [QUICKSTART.md](QUICKSTART.md), [ADVANCED.md](ADVANCED.md)
- **Troubleshooting**: [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
- **Examples**: [examples/](examples/)
- **GitHub Issues**: [Report bugs or request features](https://github.com/steveyegge/beads/issues)
- **GitHub Discussions**: [Ask questions](https://github.com/steveyegge/beads/discussions)
### How can I contribute?
Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for:
- Code contribution guidelines
- How to run tests
- Development workflow
- Issue and PR templates
### Where's the roadmap?
The roadmap lives in bd itself! Run:
```bash
bd list --priority 0 --priority 1 --json
```
Or check the GitHub Issues for feature requests and planned improvements.

267
INSTALLING.md Normal file
View File

@@ -0,0 +1,267 @@
# Installing bd
Complete installation guide for all platforms.
## Quick Install (Recommended)
### Homebrew (macOS/Linux)
```bash
brew tap steveyegge/beads
brew install bd
```
**Why Homebrew?**
- ✅ Simple one-command install
- ✅ Automatic updates via `brew upgrade`
- ✅ No need to install Go
- ✅ Handles PATH setup automatically
### Quick Install Script (All Platforms)
```bash
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
```
The installer will:
- Detect your platform (macOS/Linux, amd64/arm64)
- Install via `go install` if Go is available
- Fall back to building from source if needed
- Guide you through PATH setup if necessary
## Platform-Specific Installation
### macOS
**Via Homebrew** (recommended):
```bash
brew tap steveyegge/beads
brew install bd
```
**Via go install**:
```bash
go install github.com/steveyegge/beads/cmd/bd@latest
```
**From source**:
```bash
git clone https://github.com/steveyegge/beads
cd beads
go build -o bd ./cmd/bd
sudo mv bd /usr/local/bin/
```
### Linux
**Via Homebrew** (works on Linux too):
```bash
brew tap steveyegge/beads
brew install bd
```
**Arch Linux** (AUR):
```bash
# Install from AUR
yay -S beads-git
# or
paru -S beads-git
```
Thanks to [@v4rgas](https://github.com/v4rgas) for maintaining the AUR package!
**Via go install**:
```bash
go install github.com/steveyegge/beads/cmd/bd@latest
```
**From source**:
```bash
git clone https://github.com/steveyegge/beads
cd beads
go build -o bd ./cmd/bd
sudo mv bd /usr/local/bin/
```
### Windows 11
Beads now ships with native Windows support—no MSYS or MinGW required.
**Prerequisites:**
- [Go 1.24+](https://go.dev/dl/) installed (add `%USERPROFILE%\go\bin` to your `PATH`)
- Git for Windows
**Via PowerShell script**:
```pwsh
irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iex
```
**Via go install**:
```pwsh
go install github.com/steveyegge/beads/cmd/bd@latest
```
**From source**:
```pwsh
git clone https://github.com/steveyegge/beads
cd beads
go build -o bd.exe ./cmd/bd
Move-Item bd.exe $env:USERPROFILE\AppData\Local\Microsoft\WindowsApps\
```
**Verify installation**:
```pwsh
bd version
```
**Windows notes:**
- The background daemon listens on a loopback TCP endpoint recorded in `.beads\bd.sock`
- Keep that metadata file intact
- Allow `bd.exe` loopback traffic through any host firewall
## IDE and Editor Integrations
### Claude Code Plugin
For Claude Code users, the beads plugin provides slash commands and MCP tools.
**Prerequisites:**
1. First, install the bd CLI (see above)
2. Then install the plugin:
```bash
# In Claude Code
/plugin marketplace add steveyegge/beads
/plugin install beads
# Restart Claude Code
```
The plugin includes:
- Slash commands: `/bd-ready`, `/bd-create`, `/bd-show`, `/bd-update`, `/bd-close`, etc.
- Full MCP server with all bd tools
- Task agent for autonomous execution
See [PLUGIN.md](PLUGIN.md) for complete plugin documentation.
### MCP Server (For Sourcegraph Amp, Claude Desktop, and other MCP clients)
If you're using an MCP-compatible tool other than Claude Code:
```bash
# Using uv (recommended)
uv tool install beads-mcp
# Or using pip
pip install beads-mcp
```
**Configuration for Claude Desktop** (macOS):
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"beads": {
"command": "beads-mcp"
}
}
}
```
**Configuration for Sourcegraph Amp**:
Add to your MCP settings:
```json
{
"beads": {
"command": "beads-mcp",
"args": []
}
}
```
**What you get:**
- Full bd functionality exposed via MCP protocol
- Tools for creating, updating, listing, and closing issues
- Ready work detection and dependency management
- All without requiring Bash commands
See [integrations/beads-mcp/README.md](integrations/beads-mcp/README.md) for detailed MCP server documentation.
## Verifying Installation
After installing, verify bd is working:
```bash
bd version
bd help
```
## Troubleshooting Installation
### `bd: command not found`
bd is not in your PATH. Either:
```bash
# Check if installed
go list -f {{.Target}} github.com/steveyegge/beads/cmd/bd
# Add Go bin to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$PATH:$(go env GOPATH)/bin"
# Or reinstall
go install github.com/steveyegge/beads/cmd/bd@latest
```
### `zsh: killed bd` or crashes on macOS
Some users report crashes when running `bd init` or other commands on macOS. This is typically caused by CGO/SQLite compatibility issues.
**Workaround:**
```bash
# Build with CGO enabled
CGO_ENABLED=1 go install github.com/steveyegge/beads/cmd/bd@latest
# Or if building from source
git clone https://github.com/steveyegge/beads
cd beads
CGO_ENABLED=1 go build -o bd ./cmd/bd
sudo mv bd /usr/local/bin/
```
If you installed via Homebrew, this shouldn't be necessary as the formula already enables CGO. If you're still seeing crashes with the Homebrew version, please [file an issue](https://github.com/steveyegge/beads/issues).
## Next Steps
After installation:
1. **Initialize a project**: `cd your-project && bd init`
2. **Configure your agent**: Add bd instructions to `AGENTS.md` (see [README.md](README.md#quick-start))
3. **Learn the basics**: Run `bd quickstart` for an interactive tutorial
4. **Explore examples**: Check out the [examples/](examples/) directory
## Updating bd
### Homebrew
```bash
brew upgrade bd
```
### go install
```bash
go install github.com/steveyegge/beads/cmd/bd@latest
```
### From source
```bash
cd beads
git pull
go build -o bd ./cmd/bd
sudo mv bd /usr/local/bin/
```

1646
README.md
View File

File diff suppressed because it is too large Load Diff

410
TROUBLESHOOTING.md Normal file
View File

@@ -0,0 +1,410 @@
# Troubleshooting bd
Common issues and solutions for bd users.
## Table of Contents
- [Installation Issues](#installation-issues)
- [Database Issues](#database-issues)
- [Git and Sync Issues](#git-and-sync-issues)
- [Ready Work and Dependencies](#ready-work-and-dependencies)
- [Performance Issues](#performance-issues)
- [Agent-Specific Issues](#agent-specific-issues)
- [Platform-Specific Issues](#platform-specific-issues)
## Installation Issues
### `bd: command not found`
bd is not in your PATH. Either:
```bash
# Check if installed
go list -f {{.Target}} github.com/steveyegge/beads/cmd/bd
# Add Go bin to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$PATH:$(go env GOPATH)/bin"
# Or reinstall
go install github.com/steveyegge/beads/cmd/bd@latest
```
### `zsh: killed bd` or crashes on macOS
Some users report crashes when running `bd init` or other commands on macOS. This is typically caused by CGO/SQLite compatibility issues.
**Workaround:**
```bash
# Build with CGO enabled
CGO_ENABLED=1 go install github.com/steveyegge/beads/cmd/bd@latest
# Or if building from source
git clone https://github.com/steveyegge/beads
cd beads
CGO_ENABLED=1 go build -o bd ./cmd/bd
sudo mv bd /usr/local/bin/
```
If you installed via Homebrew, this shouldn't be necessary as the formula already enables CGO. If you're still seeing crashes with the Homebrew version, please [file an issue](https://github.com/steveyegge/beads/issues).
## Database Issues
### `database is locked`
Another bd process is accessing the database, or SQLite didn't close properly. Solutions:
```bash
# Find and kill hanging processes
ps aux | grep bd
kill <pid>
# Remove lock files (safe if no bd processes running)
rm .beads/*.db-journal .beads/*.db-wal .beads/*.db-shm
```
**Note**: bd uses a pure Go SQLite driver (`modernc.org/sqlite`) for better portability. Under extreme concurrent load (100+ simultaneous operations), you may see "database is locked" errors. This is a known limitation of the pure Go implementation and does not affect normal usage. For very high concurrency scenarios, consider using the CGO-enabled driver or PostgreSQL (planned for future release).
### `bd init` fails with "directory not empty"
`.beads/` already exists. Options:
```bash
# Use existing database
bd list # Should work if already initialized
# Or remove and reinitialize (DESTROYS DATA!)
rm -rf .beads/
bd init
```
### `failed to import: issue already exists`
You're trying to import issues that conflict with existing ones. Options:
```bash
# Skip existing issues (only import new ones)
bd import -i issues.jsonl --skip-existing
# Or clear database and re-import everything
rm .beads/*.db
bd import -i .beads/issues.jsonl
```
### Database corruption
If you suspect database corruption:
```bash
# Check database integrity
sqlite3 .beads/*.db "PRAGMA integrity_check;"
# If corrupted, reimport from JSONL
mv .beads/*.db .beads/*.db.backup
bd init
bd import -i .beads/issues.jsonl
```
## Git and Sync Issues
### Git merge conflict in `issues.jsonl`
When both sides add issues, you'll get conflicts. Resolution:
1. Open `.beads/issues.jsonl`
2. Look for `<<<<<<< HEAD` markers
3. Most conflicts can be resolved by **keeping both sides**
4. Each line is independent unless IDs conflict
5. For same-ID conflicts, keep the newest (check `updated_at`)
Example resolution:
```bash
# After resolving conflicts manually
git add .beads/issues.jsonl
git commit
bd import -i .beads/issues.jsonl # Sync to SQLite
```
See [TEXT_FORMATS.md](TEXT_FORMATS.md) for detailed merge strategies.
### ID collisions after branch merge
When merging branches where different issues were created with the same ID:
```bash
# Check for collisions
bd import -i .beads/issues.jsonl --dry-run
# Automatically resolve collisions
bd import -i .beads/issues.jsonl --resolve-collisions
```
See [ADVANCED.md#handling-import-collisions](ADVANCED.md#handling-import-collisions) for details.
### Permission denied on git hooks
Git hooks need execute permissions:
```bash
chmod +x .git/hooks/pre-commit
chmod +x .git/hooks/post-merge
chmod +x .git/hooks/post-checkout
```
Or use the installer: `cd examples/git-hooks && ./install.sh`
### Auto-sync not working
Check if auto-sync is enabled:
```bash
# Check if daemon is running
ps aux | grep "bd daemon"
# Manually export/import
bd export -o .beads/issues.jsonl
bd import -i .beads/issues.jsonl
# Install git hooks for guaranteed sync
cd examples/git-hooks && ./install.sh
```
If you disabled auto-sync with `--no-auto-flush` or `--no-auto-import`, remove those flags or use `bd sync` manually.
## Ready Work and Dependencies
### `bd ready` shows nothing but I have open issues
Those issues probably have open blockers. Check:
```bash
# See blocked issues
bd blocked
# Show dependency tree (default max depth: 50)
bd dep tree <issue-id>
# Limit tree depth to prevent deep traversals
bd dep tree <issue-id> --max-depth 10
# Remove blocking dependency if needed
bd dep remove <from-id> <to-id>
```
Remember: Only `blocks` dependencies affect ready work.
### Circular dependency errors
bd prevents dependency cycles, which break ready work detection. To fix:
```bash
# Detect all cycles
bd dep cycles
# Remove the dependency causing the cycle
bd dep remove <from-id> <to-id>
# Or redesign your dependency structure
```
### Dependencies not showing up
Check the dependency type:
```bash
# Show full issue details including dependencies
bd show <issue-id>
# Visualize the dependency tree
bd dep tree <issue-id>
```
Remember: Different dependency types have different meanings:
- `blocks` - Hard blocker, affects ready work
- `related` - Soft relationship, doesn't block
- `parent-child` - Hierarchical (child depends on parent)
- `discovered-from` - Work discovered during another issue
## Performance Issues
### Export/import is slow
For large databases (10k+ issues):
```bash
# Export only open issues
bd export --format=jsonl --status=open -o .beads/issues.jsonl
# Or filter by priority
bd export --format=jsonl --priority=0 --priority=1 -o critical.jsonl
```
Consider splitting large projects into multiple databases.
### Commands are slow
Check database size and consider compaction:
```bash
# Check database stats
bd stats
# Preview compaction candidates
bd compact --dry-run --all
# Compact old closed issues
bd compact --days 90
```
### Large JSONL files
If `.beads/issues.jsonl` is very large:
```bash
# Check file size
ls -lh .beads/issues.jsonl
# Remove old closed issues
bd compact --days 90
# Or split into multiple projects
cd ~/project/component1 && bd init --prefix comp1
cd ~/project/component2 && bd init --prefix comp2
```
## Agent-Specific Issues
### Agent creates duplicate issues
Agents may not realize an issue already exists. Prevention strategies:
- Have agents search first: `bd list --json | grep "title"`
- Use labels to mark auto-created issues: `bd create "..." -l auto-generated`
- Review and deduplicate periodically: `bd list | sort`
- Use `bd merge` to consolidate duplicates: `bd merge bd-2 --into bd-1`
### Agent gets confused by complex dependencies
Simplify the dependency structure:
```bash
# Check for overly complex trees
bd dep tree <issue-id>
# Remove unnecessary dependencies
bd dep remove <from-id> <to-id>
# Use labels instead of dependencies for loose relationships
bd label add <issue-id> related-to-feature-X
```
### Agent can't find ready work
Check if issues are blocked:
```bash
# See what's blocked
bd blocked
# See what's actually ready
bd ready --json
# Check specific issue
bd show <issue-id>
bd dep tree <issue-id>
```
### MCP server not working
Check installation and configuration:
```bash
# Verify MCP server is installed
pip list | grep beads-mcp
# Check MCP configuration
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
# Test CLI works
bd version
bd ready
# Check for daemon
ps aux | grep "bd daemon"
```
See [integrations/beads-mcp/README.md](integrations/beads-mcp/README.md) for MCP-specific troubleshooting.
## Platform-Specific Issues
### Windows: Path issues
```pwsh
# Check if bd.exe is in PATH
where.exe bd
# Add Go bin to PATH (permanently)
[Environment]::SetEnvironmentVariable(
"Path",
$env:Path + ";$env:USERPROFILE\go\bin",
[EnvironmentVariableTarget]::User
)
# Reload PATH in current session
$env:Path = [Environment]::GetEnvironmentVariable("Path", "User")
```
### Windows: Firewall blocking daemon
The daemon listens on loopback TCP. Allow `bd.exe` through Windows Firewall:
1. Open Windows Security → Firewall & network protection
2. Click "Allow an app through firewall"
3. Add `bd.exe` and enable for Private networks
4. Or disable firewall temporarily for testing
### macOS: Gatekeeper blocking execution
If macOS blocks bd:
```bash
# Remove quarantine attribute
xattr -d com.apple.quarantine /usr/local/bin/bd
# Or allow in System Preferences
# System Preferences → Security & Privacy → General → "Allow anyway"
```
### Linux: Permission denied
If you get permission errors:
```bash
# Make bd executable
chmod +x /usr/local/bin/bd
# Or install to user directory
mkdir -p ~/.local/bin
mv bd ~/.local/bin/
export PATH="$HOME/.local/bin:$PATH"
```
## Getting Help
If none of these solutions work:
1. **Check existing issues**: [GitHub Issues](https://github.com/steveyegge/beads/issues)
2. **Enable debug logging**: `bd --verbose <command>`
3. **File a bug report**: Include:
- bd version: `bd version`
- OS and architecture: `uname -a`
- Error message and full command
- Steps to reproduce
4. **Join discussions**: [GitHub Discussions](https://github.com/steveyegge/beads/discussions)
## Related Documentation
- **[README.md](README.md)** - Core features and quick start
- **[ADVANCED.md](ADVANCED.md)** - Advanced features
- **[FAQ.md](FAQ.md)** - Frequently asked questions
- **[INSTALLING.md](INSTALLING.md)** - Installation guide
- **[TEXT_FORMATS.md](TEXT_FORMATS.md)** - JSONL format and merge strategies