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

Refactor AGENTS.md: extract supplemental docs

Browse Source 
- Create docs/DAEMON.md (daemon mgmt, event-driven mode)
- Create docs/GIT_INTEGRATION.md (worktrees, conflicts, merge drivers)
- Create docs/CLI_REFERENCE.md (comprehensive command examples)
- Reduce AGENTS.md from 1047 → 906 lines (13% reduction)
- Add Agent Mail optional workflow section (bd-2cvu)

Improves navigability while preserving all content.

Amp-Thread-ID: https://ampcode.com/threads/T-f8161cc4-d6d2-4f23-8854-4834dbdedb26
Co-authored-by: Amp <amp@ampcode.com>
This commit is contained in:
Steve Yegge
2025-11-08 01:03:28 -08:00
parent ef1634d850
commit 826a3b2047
4 changed files with 1562 additions and 520 deletions
Download Patch File Download Diff File Expand all files Collapse all files

596
AGENTS.md
View File

@@ -142,337 +142,55 @@ If you must use separate MCP servers:
### CLI Quick Reference
If you're not using the MCP server, here are the CLI commands:
**Essential commands for AI agents:**
```bash
# Check database path and daemon status
bd info --json
# Find work
bd ready --json # Unblocked issues
bd stale --days 30 --json # Forgotten issues
# Find ready work (no blockers)
bd ready --json
# Create and manage issues
bd create "Issue title" -t bug|feature|task -p 0-4 --json
bd create "Found bug" -p 1 --deps discovered-from:<parent-id> --json
bd update <id> --status in_progress --json
bd close <id> --reason "Done" --json
# Find stale issues (not updated recently)
bd stale --days 30 --json # Default: 30 days
bd stale --days 90 --status in_progress --json # Filter by status
bd stale --limit 20 --json # Limit results
# Search and filter
bd list --status open --priority 1 --json
bd list --label-any urgent,critical --json
bd show <id> --json
# Create new issue
# IMPORTANT: Always quote titles and descriptions with double quotes
bd create "Issue title" -t bug|feature|task -p 0-4 -d "Description" --json
# Create with explicit ID (for parallel workers)
bd create "Issue title" --id worker1-100 -p 1 --json
# Create with labels (--labels or --label work)
bd create "Issue title" -t bug -p 1 -l bug,critical --json
bd create "Issue title" -t bug -p 1 --label bug,critical --json
# Examples with special characters (all require quoting):
bd create "Fix: auth doesn't validate tokens" -t bug -p 1 --json
bd create "Add support for OAuth 2.0" -d "Implement RFC 6749 (OAuth 2.0 spec)" --json
# Create multiple issues from markdown file
bd create -f feature-plan.md --json
# Create epic with hierarchical child tasks
bd create "Auth System" -t epic -p 1 --json # Returns: bd-a3f8e9
bd create "Login UI" -p 1 --json # Auto-assigned: bd-a3f8e9.1
bd create "Backend validation" -p 1 --json # Auto-assigned: bd-a3f8e9.2
bd create "Tests" -p 1 --json # Auto-assigned: bd-a3f8e9.3
# Update one or more issues
bd update <id> [<id>...] --status in_progress --json
bd update <id> [<id>...] --priority 1 --json
# Edit issue fields in $EDITOR (HUMANS ONLY - not for agents)
# NOTE: This command is intentionally NOT exposed via the MCP server
# Agents should use 'bd update' with field-specific parameters instead
bd edit <id> # Edit description
bd edit <id> --title # Edit title
bd edit <id> --design # Edit design notes
bd edit <id> --notes # Edit notes
bd edit <id> --acceptance # Edit acceptance criteria
# Link discovered work (old way)
bd dep add <discovered-id> <parent-id> --type discovered-from
# Create and link in one command (new way)
bd create "Issue title" -t bug -p 1 --deps discovered-from:<parent-id> --json
# Label management (supports multiple IDs)
bd label add <id> [<id>...] <label> --json
bd label remove <id> [<id>...] <label> --json
bd label list <id> --json
bd label list-all --json
# Filter and search issues
bd list --status open --priority 1 --json # Status and priority
bd list --assignee alice --json # By assignee
bd list --type bug --json # By issue type
bd list --label bug,critical --json # Labels (AND: must have ALL)
bd list --label-any frontend,backend --json # Labels (OR: has ANY)
bd list --id bd-123,bd-456 --json # Specific IDs
bd list --title "auth" --json # Title search (substring)
# Pattern matching (case-insensitive substring)
bd list --title-contains "auth" --json # Search in title
bd list --desc-contains "implement" --json # Search in description
bd list --notes-contains "TODO" --json # Search in notes
# Date range filters (YYYY-MM-DD or RFC3339)
bd list --created-after 2024-01-01 --json # Created after date
bd list --created-before 2024-12-31 --json # Created before date
bd list --updated-after 2024-06-01 --json # Updated after date
bd list --updated-before 2024-12-31 --json # Updated before date
bd list --closed-after 2024-01-01 --json # Closed after date
bd list --closed-before 2024-12-31 --json # Closed before date
# Empty/null checks
bd list --empty-description --json # Issues with no description
bd list --no-assignee --json # Unassigned issues
bd list --no-labels --json # Issues with no labels
# Priority ranges
bd list --priority-min 0 --priority-max 1 --json # P0 and P1 only
bd list --priority-min 2 --json # P2 and below
# Combine filters
bd list --status open --priority 1 --label-any urgent,critical --no-assignee --json
# Complete work (supports multiple IDs)
bd close <id> [<id>...] --reason "Done" --json
# Reopen closed issues (supports multiple IDs)
bd reopen <id> [<id>...] --reason "Reopening" --json
# Clean up closed issues (bulk deletion)
bd cleanup --force --json # Delete ALL closed issues
bd cleanup --older-than 30 --force --json # Delete closed >30 days ago
bd cleanup --dry-run --json # Preview what would be deleted
bd cleanup --older-than 90 --cascade --force --json # Delete old + dependents
# Show dependency tree
bd dep tree <id>
# Get issue details (supports multiple IDs)
bd show <id> [<id>...] --json
# Rename issue prefix (e.g., from 'knowledge-work-' to 'kw-')
bd rename-prefix kw- --dry-run # Preview changes
bd rename-prefix kw- --json # Apply rename
# Agent-driven compaction (memory decay)
bd compact --analyze --json # Get candidates for review
bd compact --analyze --tier 1 --limit 10 --json # Limited batch
bd compact --apply --id bd-42 --summary summary.txt # Apply compaction
bd compact --apply --id bd-42 --summary - < summary.txt # From stdin
bd compact --stats --json # Show statistics
# Legacy AI-powered compaction (requires ANTHROPIC_API_KEY)
bd compact --auto --dry-run --all # Preview
bd compact --auto --all --tier 1 # Auto-compact tier 1
# Restore compacted issue from git history
bd restore <id> # View full history at time of compaction
# Import issues from JSONL
bd import -i .beads/issues.jsonl --dry-run # Preview changes
bd import -i .beads/issues.jsonl # Import and update issues
bd import -i .beads/issues.jsonl --dedupe-after # Import + detect duplicates
# Note: Import automatically handles missing parents!
# - If a hierarchical child's parent is missing (e.g., bd-abc.1 but no bd-abc)
# - bd will search the JSONL history for the parent
# - If found, creates a tombstone placeholder (Status=Closed, Priority=4)
# - Dependencies are also resurrected on best-effort basis
# - This prevents import failures after parent deletion
# Find and merge duplicate issues
bd duplicates # Show all duplicates
bd duplicates --auto-merge # Automatically merge all
bd duplicates --dry-run # Preview merge operations
# Merge specific duplicate issues
bd merge <source-id...> --into <target-id> --json # Consolidate duplicates
bd merge bd-42 bd-43 --into bd-41 --dry-run # Preview merge
# Migrate databases after version upgrade
bd migrate # Detect and migrate old databases
bd migrate --dry-run # Preview migration
bd migrate --cleanup --yes # Migrate and remove old files
# AI-supervised migration (check before running bd migrate)
bd migrate --inspect --json # Show migration plan for AI agents
bd info --schema --json # Get schema, tables, config, sample IDs
# Workflow: AI agents should inspect first, then migrate
# 1. Run --inspect to see pending migrations and warnings
# 2. Check for missing_config (like issue_prefix)
# 3. Review invariants_to_check for safety guarantees
# 4. If warnings exist, fix config issues first
# 5. Then run bd migrate safely
# Sync (CRITICAL at end of session!)
bd sync # Force immediate export/commit/push
```
**Migration safety:** The system verifies data integrity invariants after migrations:
- **required_config_present**: Ensures issue_prefix and schema_version are set
- **foreign_keys_valid**: No orphaned dependencies or labels
- **issue_count_stable**: Issue count doesn't decrease unexpectedly
These invariants prevent data loss and would have caught issues like GH #201 (missing issue_prefix after migration).
**For comprehensive CLI documentation**, see [docs/CLI_REFERENCE.md](docs/CLI_REFERENCE.md).
### Managing Daemons
bd runs a background daemon per workspace for auto-sync and RPC operations. Use `bd daemons` to manage multiple daemons:
bd runs a background daemon per workspace for auto-sync and RPC operations:
```bash
# List all running daemons
bd daemons list --json
# Check health (version mismatches, stale sockets)
bd daemons health --json
# Stop a specific daemon
bd daemons stop /path/to/workspace --json
bd daemons stop 12345 --json # By PID
# Restart a specific daemon
bd daemons restart /path/to/workspace --json
bd daemons restart 12345 --json # By PID
# View daemon logs
bd daemons logs /path/to/workspace -n 100
bd daemons logs 12345 -f # Follow mode
# Stop all daemons
bd daemons killall --json
bd daemons killall --force --json # Force kill if graceful fails
bd daemons list --json # List all running daemons
bd daemons health --json # Check for version mismatches
bd daemons logs . -n 100 # View daemon logs
bd daemons killall --json # Restart all daemons
```
**When to use:**
**After upgrading bd**: Run `bd daemons killall` to restart all daemons with new version.
- **After upgrading bd**: Run `bd daemons health` to check for version mismatches, then `bd daemons killall` to restart all daemons with the new version
- **Debugging**: Use `bd daemons logs <workspace>` to view daemon logs
- **Cleanup**: `bd daemons list` auto-removes stale sockets
**Troubleshooting:**
- **Stale sockets**: `bd daemons list` auto-cleans them
- **Version mismatch**: `bd daemons killall` then let daemons auto-start on next command
- **Daemon won't stop**: `bd daemons killall --force`
See [commands/daemons.md](commands/daemons.md) for detailed documentation.
**For complete daemon management**, see [docs/DAEMON.md](docs/DAEMON.md).
### Web Interface (Monitor)
**Note for AI Agents:** The monitor is primarily for human visualization and supervision. Agents should continue using the CLI with `--json` flags.
bd includes a built-in web interface for real-time issue monitoring:
bd includes a built-in web interface for human visualization:
```bash
bd monitor # Start on localhost:8080
bd monitor --port 3000 # Custom port
bd monitor --host 0.0.0.0 --port 80 # Public access
bd monitor # Start on localhost:8080
bd monitor --port 3000 # Custom port
```
**Features:**
- Real-time issue table with filtering (status, priority)
- Click-through to detailed issue view
- WebSocket updates (when daemon is running)
- Responsive mobile design
- Statistics dashboard
**When humans might use it:**
- Supervising AI agent work in real-time
- Quick project status overview
- Mobile access to issue tracking
- Team dashboard for shared visibility
**AI agents should NOT:**
- Parse HTML from the monitor (use `--json` flags instead)
- Try to interact with the web UI programmatically
- Use monitor for data retrieval (use CLI commands)
### Event-Driven Daemon Mode (Experimental)
**NEW in v0.16+**: The daemon supports an experimental event-driven mode that replaces 5-second polling with instant reactivity.
**Benefits:**
- ⚡ **<500ms latency** (vs ~5000ms with polling)
- 🔋 **~60% less CPU usage** (no continuous polling)
- 🎯 **Instant sync** on mutations and file changes
- 🛡️ **Dropped events safety net** prevents data loss
**How it works:**
- **FileWatcher** monitors `.beads/issues.jsonl` and `.git/refs/heads` using platform-native APIs:
- Linux: `inotify`
- macOS: `FSEvents` (via kqueue)
- Windows: `ReadDirectoryChangesW`
- **Mutation events** from RPC operations (create, update, close) trigger immediate export
- **Debouncer** batches rapid changes (500ms window) to avoid export storms
- **Polling fallback** if fsnotify unavailable (e.g., network filesystems)
**Opt-In (Phase 1):**
Event-driven mode is opt-in during Phase 1. To enable:
```bash
# Enable event-driven mode for a single daemon
BEADS_DAEMON_MODE=events bd daemon start
# Or set globally in your shell profile
export BEADS_DAEMON_MODE=events
# Restart all daemons to apply
bd daemons killall
# Next bd command will auto-start daemon with new mode
```
**Available modes:**
- `poll` (default) - Traditional 5-second polling, stable and battle-tested
- `events` - New event-driven mode, experimental but thoroughly tested
**Troubleshooting:**
If the watcher fails to start:
- Check daemon logs: `bd daemons logs /path/to/workspace -n 100`
- Look for "File watcher unavailable" warnings
- Common causes:
- Network filesystem (NFS, SMB) - fsnotify may not work
- Container environment - may need privileged mode
- Resource limits - check `ulimit -n` (open file descriptors)
**Fallback behavior:**
- If `BEADS_DAEMON_MODE=events` but watcher fails, daemon falls back to polling automatically
- Set `BEADS_WATCHER_FALLBACK=false` to disable fallback and require fsnotify
**Disable polling fallback:**
```bash
# Require fsnotify, fail if unavailable
BEADS_WATCHER_FALLBACK=false BEADS_DAEMON_MODE=events bd daemon start
```
**Switch back to polling:**
```bash
# Explicitly use polling mode
BEADS_DAEMON_MODE=poll bd daemon start
# Or unset to use default
unset BEADS_DAEMON_MODE
bd daemons killall # Restart with default (poll) mode
```
**Future (Phase 2):** Event-driven mode will become the default once it's proven stable in production use.
**AI agents**: Continue using CLI with `--json` flags. The monitor is for human supervision only.
### Workflow
@@ -485,6 +203,50 @@ bd daemons killall # Restart with default (poll) mode
5. **Complete**: `bd close <id> --reason "Implemented"`
6. **Sync at end of session**: `bd sync` (see "Agent Session Workflow" below)
### Optional: Agent Mail for Multi-Agent Coordination
**For multi-agent workflows only** - if multiple AI agents work on the same repository simultaneously, consider using Agent Mail for real-time coordination:
**With Agent Mail enabled:**
```bash
# Configure environment (one-time per session)
export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
export BEADS_AGENT_NAME=assistant-alpha
export BEADS_PROJECT_ID=my-project
# Workflow (identical commands)
bd ready # Shows available work
bd update bd-42 --status in_progress # Reserves issue instantly (<100ms)
# ... work on issue ...
bd close bd-42 "Done" # Releases reservation automatically
```
**Without Agent Mail (git-only mode):**
```bash
# No environment variables needed
bd ready # Shows available work
bd update bd-42 --status in_progress # Updates via git sync (2-5s latency)
# ... work on issue ...
bd close bd-42 "Done" # Updates via git sync
```
**Key differences:**
- **Latency**: <100ms (Agent Mail) vs 2-5s (git-only)
- **Collision prevention**: Instant reservation (Agent Mail) vs eventual consistency (git)
- **Setup**: Requires server + env vars (Agent Mail) vs zero config (git-only)
**When to use Agent Mail:**
- ✅ Multiple agents working concurrently
- ✅ Frequent status updates (high collision risk)
- ✅ Real-time coordination needed
**When to skip:**
- ✅ Single agent workflows
- ✅ Infrequent updates (low collision risk)
- ✅ Simplicity preferred over latency
See [docs/AGENT_MAIL.md](docs/AGENT_MAIL.md) for complete setup, troubleshooting, and architecture details.
### Issue Types
- `bug` - Something broken that needs fixing
@@ -665,58 +427,15 @@ func TestMyFeature(t *testing.T) {
The 30-second debounce provides a **transaction window** for batch operations - multiple issue changes within 30 seconds get flushed together, avoiding commit spam.
### Protected Branch Workflow
### Git Integration
**If your repository uses protected branches (GitHub, GitLab, etc.)**, beads can commit to a separate branch instead of `main`:
**Auto-sync**: bd automatically exports to JSONL (30s debounce), imports after `git pull`, and optionally commits/pushes.
```bash
# Initialize with separate sync branch
bd init --branch beads-metadata
**Protected branches**: Use `bd init --branch beads-metadata` to commit to separate branch. See [docs/PROTECTED_BRANCHES.md](docs/PROTECTED_BRANCHES.md).
# Or configure existing setup
bd config set sync.branch beads-metadata
```
**Git worktrees**: Daemon mode NOT supported. Use `bd --no-daemon` for all commands. See [docs/GIT_INTEGRATION.md](docs/GIT_INTEGRATION.md).
**How it works:**
- Beads commits issue updates to `beads-metadata` instead of `main`
- Uses git worktrees (lightweight checkouts) in `.git/beads-worktrees/`
- Your main working directory is never affected
- Periodically merge `beads-metadata` back to `main` via pull request
**Daily workflow (unchanged for agents):**
```bash
# Agents work normally - no changes needed!
bd create "Fix authentication" -t bug -p 1
bd update bd-a1b2 --status in_progress
bd close bd-a1b2 "Fixed"
```
All changes automatically commit to `beads-metadata` branch (if daemon is running with `--auto-commit`).
**Merging to main (humans):**
```bash
# Check what's changed
bd sync --status
# Option 1: Create pull request
git push origin beads-metadata
# Then create PR on GitHub/GitLab
# Option 2: Direct merge (if allowed)
bd sync --merge
```
**Benefits:**
- ✅ Works with protected `main` branches
- ✅ No disruption to agent workflows
- ✅ Platform-agnostic (works on any git platform)
- ✅ Backward compatible (opt-in via config)
**See [docs/PROTECTED_BRANCHES.md](docs/PROTECTED_BRANCHES.md) for complete setup guide, troubleshooting, and examples.**
**Merge conflicts**: Rare with hash IDs. If conflicts occur, use `git checkout --theirs/.beads/beads.jsonl` and `bd import`. See [docs/GIT_INTEGRATION.md](docs/GIT_INTEGRATION.md).
### Landing the Plane
@@ -829,140 +548,7 @@ Without the pre-push hook, you can have database changes committed locally but s
See [examples/git-hooks/README.md](examples/git-hooks/README.md) for details.
### 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 Git Merge Conflicts
**With hash-based IDs (v0.20.1+), ID collisions are eliminated!** Different issues get different hash IDs, so most git merges succeed cleanly.
**When git merge conflicts occur:**
Git conflicts in `.beads/beads.jsonl` happen when the same issue is modified on both branches (different timestamps/fields). This is a **same-issue update conflict**, not an ID collision. Conflicts are rare in practice since hash IDs prevent structural collisions.
**Automatic detection:**
bd automatically detects conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`) and shows clear resolution steps:
- `bd import` rejects files with conflict markers and shows resolution commands
- `bd validate --checks=conflicts` scans for conflicts in JSONL
**Resolution workflow:**
```bash
# After git merge creates conflict in .beads/beads.jsonl
# Option 1: Accept their version (remote)
git checkout --theirs .beads/beads.jsonl
bd import -i .beads/beads.jsonl
# Option 2: Keep our version (local)
git checkout --ours .beads/beads.jsonl
bd import -i .beads/beads.jsonl
# Option 3: Manual resolution in editor
# Edit .beads/beads.jsonl to remove conflict markers
bd import -i .beads/beads.jsonl
# Commit the merge
git add .beads/beads.jsonl
git commit
```
**Note:** `bd import` automatically handles updates - same ID with different content is a normal update operation. No special flags needed. If you accidentally modified the same issue in both branches, just pick whichever version is more complete.
### Intelligent Merge Driver (Auto-Configured)
**As of v0.21+, bd automatically configures its own merge driver during `bd init`.** This uses the beads-merge algorithm (by @neongreen, vendored into bd) to provide intelligent JSONL merging and prevent conflicts when multiple branches modify issues.
**What it does:**
- Performs field-level 3-way merging (not line-by-line)
- Matches issues by identity (id + created_at + created_by)
- Smart field merging: timestamps→max, dependencies→union, status/priority→3-way
- Outputs conflict markers only for unresolvable conflicts
- Automatically configured during `bd init` (both interactive and `--quiet` modes)
**Auto-configuration (happens automatically):**
```bash
# During bd init, these are configured:
git config merge.beads.driver "bd merge %A %O %L %R"
git config merge.beads.name "bd JSONL merge driver"
# .gitattributes entry: .beads/beads.jsonl merge=beads
```
**Manual setup (if skipped with `--skip-merge-driver`):**
```bash
git config merge.beads.driver "bd merge %A %O %L %R"
git config merge.beads.name "bd JSONL merge driver"
echo ".beads/beads.jsonl merge=beads" >> .gitattributes
```
**Alternative: Standalone beads-merge binary**
If you prefer to use the standalone beads-merge binary (same algorithm, different package):
```bash
# Install (requires Go 1.21+)
git clone https://github.com/neongreen/mono.git
cd mono/beads-merge
go install
# Configure Git merge driver (same algorithm as bd merge)
git config merge.beads.name "JSONL merge driver for beads"
git config merge.beads.driver "beads-merge %A %O %A %B"
```
**For Jujutsu users**, add to `~/.jjconfig.toml`:
```toml
[merge-tools.beads-merge]
program = "beads-merge"
merge-args = ["$output", "$base", "$left", "$right"]
merge-conflict-exit-codes = [1]
```
Then resolve with: `jj resolve --tool=beads-merge`
**How it works**: During `git merge`, beads-merge merges JSONL files issue-by-issue instead of line-by-line. This prevents spurious conflicts from line renumbering or timestamp updates. If conflicts remain, they're marked in standard format for manual resolution.
## Current Project Status
@@ -984,37 +570,7 @@ We're working toward 1.0. Key blockers tracked in bd. Run:
bd dep tree bd-8 # Show 1.0 epic dependencies
```
## Exclusive Lock Protocol (Advanced)
**For external tools that need full database control** (e.g., CI/CD, deterministic execution systems):
The bd daemon respects exclusive locks via `.beads/.exclusive-lock` file. When this lock exists:
- Daemon skips all operations for the locked database
- External tool has complete control over git sync and database operations
- Stale locks (dead process) are automatically cleaned up
**Use case:** Tools like VibeCoder that need deterministic execution without daemon interference.
See [EXCLUSIVE_LOCK.md](EXCLUSIVE_LOCK.md) for:
- Lock file format (JSON schema)
- Creating and releasing locks (Go/shell examples)
- Stale lock detection behavior
- Integration testing guidance
**Quick example:**
```bash
# Create lock
echo '{"holder":"my-tool","pid":'$$',"hostname":"'$(hostname)'","started_at":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","version":"1.0.0"}' > .beads/.exclusive-lock
# Do work...
bd create "My issue" -p 1
# Release lock
rm .beads/.exclusive-lock
```
## Common Tasks

464
docs/CLI_REFERENCE.md Normal file
View File

@@ -0,0 +1,464 @@
# CLI Command Reference
**For:** AI agents and developers using bd command-line interface
**Version:** 0.21.0+
## Quick Navigation
- [Basic Operations](#basic-operations)
- [Issue Management](#issue-management)
- [Dependencies & Labels](#dependencies--labels)
- [Filtering & Search](#filtering--search)
- [Advanced Operations](#advanced-operations)
- [Database Management](#database-management)
## Basic Operations
### Check Status
```bash
# Check database path and daemon status
bd info --json
# Example output:
# {
# "database_path": "/path/to/.beads/beads.db",
# "issue_prefix": "bd",
# "daemon_running": true,
# "agent_mail_enabled": false
# }
```
### Find Work
```bash
# Find ready work (no blockers)
bd ready --json
# Find stale issues (not updated recently)
bd stale --days 30 --json # Default: 30 days
bd stale --days 90 --status in_progress --json # Filter by status
bd stale --limit 20 --json # Limit results
```
## Issue Management
### Create Issues
```bash
# Basic creation
# IMPORTANT: Always quote titles and descriptions with double quotes
bd create "Issue title" -t bug|feature|task -p 0-4 -d "Description" --json
# Create with explicit ID (for parallel workers)
bd create "Issue title" --id worker1-100 -p 1 --json
# Create with labels (--labels or --label work)
bd create "Issue title" -t bug -p 1 -l bug,critical --json
bd create "Issue title" -t bug -p 1 --label bug,critical --json
# Examples with special characters (all require quoting):
bd create "Fix: auth doesn't validate tokens" -t bug -p 1 --json
bd create "Add support for OAuth 2.0" -d "Implement RFC 6749 (OAuth 2.0 spec)" --json
# Create multiple issues from markdown file
bd create -f feature-plan.md --json
# Create epic with hierarchical child tasks
bd create "Auth System" -t epic -p 1 --json # Returns: bd-a3f8e9
bd create "Login UI" -p 1 --json # Auto-assigned: bd-a3f8e9.1
bd create "Backend validation" -p 1 --json # Auto-assigned: bd-a3f8e9.2
bd create "Tests" -p 1 --json # Auto-assigned: bd-a3f8e9.3
# Create and link discovered work (one command)
bd create "Found bug" -t bug -p 1 --deps discovered-from:<parent-id> --json
```
### Update Issues
```bash
# Update one or more issues
bd update <id> [<id>...] --status in_progress --json
bd update <id> [<id>...] --priority 1 --json
# Edit issue fields in $EDITOR (HUMANS ONLY - not for agents)
# NOTE: This command is intentionally NOT exposed via the MCP server
# Agents should use 'bd update' with field-specific parameters instead
bd edit <id> # Edit description
bd edit <id> --title # Edit title
bd edit <id> --design # Edit design notes
bd edit <id> --notes # Edit notes
bd edit <id> --acceptance # Edit acceptance criteria
```
### Close/Reopen Issues
```bash
# Complete work (supports multiple IDs)
bd close <id> [<id>...] --reason "Done" --json
# Reopen closed issues (supports multiple IDs)
bd reopen <id> [<id>...] --reason "Reopening" --json
```
### View Issues
```bash
# Show dependency tree
bd dep tree <id>
# Get issue details (supports multiple IDs)
bd show <id> [<id>...] --json
```
## Dependencies & Labels
### Dependencies
```bash
# Link discovered work (old way - two commands)
bd dep add <discovered-id> <parent-id> --type discovered-from
# Create and link in one command (new way - preferred)
bd create "Issue title" -t bug -p 1 --deps discovered-from:<parent-id> --json
```
### Labels
```bash
# Label management (supports multiple IDs)
bd label add <id> [<id>...] <label> --json
bd label remove <id> [<id>...] <label> --json
bd label list <id> --json
bd label list-all --json
```
## Filtering & Search
### Basic Filters
```bash
# Filter by status, priority, type
bd list --status open --priority 1 --json # Status and priority
bd list --assignee alice --json # By assignee
bd list --type bug --json # By issue type
bd list --id bd-123,bd-456 --json # Specific IDs
```
### Label Filters
```bash
# Labels (AND: must have ALL)
bd list --label bug,critical --json
# Labels (OR: has ANY)
bd list --label-any frontend,backend --json
```
### Text Search
```bash
# Title search (substring)
bd list --title "auth" --json
# Pattern matching (case-insensitive substring)
bd list --title-contains "auth" --json # Search in title
bd list --desc-contains "implement" --json # Search in description
bd list --notes-contains "TODO" --json # Search in notes
```
### Date Range Filters
```bash
# Date range filters (YYYY-MM-DD or RFC3339)
bd list --created-after 2024-01-01 --json # Created after date
bd list --created-before 2024-12-31 --json # Created before date
bd list --updated-after 2024-06-01 --json # Updated after date
bd list --updated-before 2024-12-31 --json # Updated before date
bd list --closed-after 2024-01-01 --json # Closed after date
bd list --closed-before 2024-12-31 --json # Closed before date
```
### Empty/Null Checks
```bash
# Empty/null checks
bd list --empty-description --json # Issues with no description
bd list --no-assignee --json # Unassigned issues
bd list --no-labels --json # Issues with no labels
```
### Priority Ranges
```bash
# Priority ranges
bd list --priority-min 0 --priority-max 1 --json # P0 and P1 only
bd list --priority-min 2 --json # P2 and below
```
### Combine Filters
```bash
# Combine multiple filters
bd list --status open --priority 1 --label-any urgent,critical --no-assignee --json
```
## Advanced Operations
### Cleanup
```bash
# Clean up closed issues (bulk deletion)
bd cleanup --force --json # Delete ALL closed issues
bd cleanup --older-than 30 --force --json # Delete closed >30 days ago
bd cleanup --dry-run --json # Preview what would be deleted
bd cleanup --older-than 90 --cascade --force --json # Delete old + dependents
```
### Duplicate Detection & Merging
```bash
# Find and merge duplicate issues
bd duplicates # Show all duplicates
bd duplicates --auto-merge # Automatically merge all
bd duplicates --dry-run # Preview merge operations
# Merge specific duplicate issues
bd merge <source-id...> --into <target-id> --json # Consolidate duplicates
bd merge bd-42 bd-43 --into bd-41 --dry-run # Preview merge
```
### Compaction (Memory Decay)
```bash
# Agent-driven compaction
bd compact --analyze --json # Get candidates for review
bd compact --analyze --tier 1 --limit 10 --json # Limited batch
bd compact --apply --id bd-42 --summary summary.txt # Apply compaction
bd compact --apply --id bd-42 --summary - < summary.txt # From stdin
bd compact --stats --json # Show statistics
# Legacy AI-powered compaction (requires ANTHROPIC_API_KEY)
bd compact --auto --dry-run --all # Preview
bd compact --auto --all --tier 1 # Auto-compact tier 1
# Restore compacted issue from git history
bd restore <id> # View full history at time of compaction
```
### Rename Prefix
```bash
# Rename issue prefix (e.g., from 'knowledge-work-' to 'kw-')
bd rename-prefix kw- --dry-run # Preview changes
bd rename-prefix kw- --json # Apply rename
```
## Database Management
### Import/Export
```bash
# Import issues from JSONL
bd import -i .beads/issues.jsonl --dry-run # Preview changes
bd import -i .beads/issues.jsonl # Import and update issues
bd import -i .beads/issues.jsonl --dedupe-after # Import + detect duplicates
# Note: Import automatically handles missing parents!
# - If a hierarchical child's parent is missing (e.g., bd-abc.1 but no bd-abc)
# - bd will search the JSONL history for the parent
# - If found, creates a tombstone placeholder (Status=Closed, Priority=4)
# - Dependencies are also resurrected on best-effort basis
# - This prevents import failures after parent deletion
```
### Migration
```bash
# Migrate databases after version upgrade
bd migrate # Detect and migrate old databases
bd migrate --dry-run # Preview migration
bd migrate --cleanup --yes # Migrate and remove old files
# AI-supervised migration (check before running bd migrate)
bd migrate --inspect --json # Show migration plan for AI agents
bd info --schema --json # Get schema, tables, config, sample IDs
```
**Migration workflow for AI agents:**
1. Run `--inspect` to see pending migrations and warnings
2. Check for `missing_config` (like issue_prefix)
3. Review `invariants_to_check` for safety guarantees
4. If warnings exist, fix config issues first
5. Then run `bd migrate` safely
**Migration safety invariants:**
- **required_config_present**: Ensures issue_prefix and schema_version are set
- **foreign_keys_valid**: No orphaned dependencies or labels
- **issue_count_stable**: Issue count doesn't decrease unexpectedly
These invariants prevent data loss and would have caught issues like GH #201 (missing issue_prefix after migration).
### Daemon Management
See [docs/DAEMON.md](DAEMON.md) for complete daemon management reference.
```bash
# List all running daemons
bd daemons list --json
# Check health (version mismatches, stale sockets)
bd daemons health --json
# Stop/restart specific daemon
bd daemons stop /path/to/workspace --json
bd daemons restart 12345 --json # By PID
# View daemon logs
bd daemons logs /path/to/workspace -n 100
bd daemons logs 12345 -f # Follow mode
# Stop all daemons
bd daemons killall --json
bd daemons killall --force --json # Force kill if graceful fails
```
### Sync Operations
```bash
# Manual sync (force immediate export/import/commit/push)
bd sync
# What it does:
# 1. Export pending changes to JSONL
# 2. Commit to git
# 3. Pull from remote
# 4. Import any updates
# 5. Push to remote
```
## Issue Types
- `bug` - Something broken that needs fixing
- `feature` - New functionality
- `task` - Work item (tests, docs, refactoring)
- `epic` - Large feature composed of multiple issues (supports hierarchical children)
- `chore` - Maintenance work (dependencies, tooling)
**Hierarchical children:** Epics can have child issues with dotted IDs (e.g., `bd-a3f8e9.1`, `bd-a3f8e9.2`). Children are auto-numbered sequentially. Up to 3 levels of nesting supported.
## Priorities
- `0` - Critical (security, data loss, broken builds)
- `1` - High (major features, important bugs)
- `2` - Medium (nice-to-have features, minor bugs)
- `3` - Low (polish, optimization)
- `4` - Backlog (future ideas)
## Dependency Types
- `blocks` - Hard dependency (issue X blocks issue Y)
- `related` - Soft relationship (issues are connected)
- `parent-child` - Epic/subtask relationship
- `discovered-from` - Track issues discovered during work
Only `blocks` dependencies affect the ready work queue.
**Note:** When creating an issue with a `discovered-from` dependency, the new issue automatically inherits the parent's `source_repo` field.
## Output Formats
### JSON Output (Recommended for Agents)
Always use `--json` flag for programmatic use:
```bash
# Single issue
bd show bd-42 --json
# List of issues
bd ready --json
# Operation result
bd create "Issue" -p 1 --json
```
### Human-Readable Output
Default output without `--json`:
```bash
bd ready
# bd-42 Fix authentication bug [P1, bug, in_progress]
# bd-43 Add user settings page [P2, feature, open]
```
## Common Patterns for AI Agents
### Claim and Complete Work
```bash
# 1. Find available work
bd ready --json
# 2. Claim issue
bd update bd-42 --status in_progress --json
# 3. Work on it...
# 4. Close when done
bd close bd-42 --reason "Implemented and tested" --json
```
### Discover and Link Work
```bash
# While working on bd-100, discover a bug
# Old way (two commands):
bd create "Found auth bug" -t bug -p 1 --json # Returns bd-101
bd dep add bd-101 bd-100 --type discovered-from
# New way (one command):
bd create "Found auth bug" -t bug -p 1 --deps discovered-from:bd-100 --json
```
### Batch Operations
```bash
# Update multiple issues at once
bd update bd-41 bd-42 bd-43 --priority 0 --json
# Close multiple issues
bd close bd-41 bd-42 bd-43 --reason "Batch completion" --json
# Add label to multiple issues
bd label add bd-41 bd-42 bd-43 urgent --json
```
### Session Workflow
```bash
# Start of session
bd ready --json # Find work
# During session
bd create "..." -p 1 --json
bd update bd-42 --status in_progress --json
# ... work ...
# End of session (IMPORTANT!)
bd sync # Force immediate sync, bypass debounce
```
**ALWAYS run `bd sync` at end of agent sessions** to ensure changes are committed/pushed immediately.
## See Also
- [AGENTS.md](../AGENTS.md) - Main agent workflow guide
- [DAEMON.md](DAEMON.md) - Daemon management and event-driven mode
- [GIT_INTEGRATION.md](GIT_INTEGRATION.md) - Git workflows and merge strategies
- [LABELS.md](../LABELS.md) - Label system guide
- [README.md](../README.md) - User documentation

495
docs/DAEMON.md Normal file
View File

@@ -0,0 +1,495 @@
# Daemon Management Guide
**For:** AI agents and developers managing bd background processes
**Version:** 0.21.0+
## Overview
bd runs a background daemon per workspace for auto-sync, RPC operations, and real-time monitoring. This guide covers daemon management, event-driven mode, and troubleshooting.
## Architecture
**Per-Workspace Model (LSP-style):**
```
MCP Server (one instance)
↓
Per-Project Daemons (one per workspace)
↓
SQLite Databases (complete isolation)
```
Each workspace gets its own daemon:
- Socket at `.beads/bd.sock` (`.beads/bd.pipe` on Windows)
- Auto-starts on first command (unless disabled)
- Handles auto-sync, batching, background operations
- Complete database isolation (no cross-project pollution)
## Managing Daemons
### List All Running Daemons
```bash
# See all daemons across workspaces
bd daemons list --json
# Example output:
# [
# {
# "workspace": "/Users/alice/projects/webapp",
# "pid": 12345,
# "socket": "/Users/alice/projects/webapp/.beads/bd.sock",
# "version": "0.21.0",
# "uptime_seconds": 3600
# }
# ]
```
### Check Daemon Health
```bash
# Check for version mismatches, stale sockets
bd daemons health --json
# Example output:
# {
# "healthy": false,
# "issues": [
# {
# "workspace": "/Users/alice/old-project",
# "issue": "version_mismatch",
# "daemon_version": "0.20.0",
# "cli_version": "0.21.0"
# }
# ]
# }
```
**When to use:**
- After upgrading bd (check for version mismatches)
- Debugging sync issues
- Periodic health monitoring
### Stop/Restart Daemons
```bash
# Stop specific daemon by workspace path
bd daemons stop /path/to/workspace --json
# Stop by PID
bd daemons stop 12345 --json
# Restart (stop + auto-start on next command)
bd daemons restart /path/to/workspace --json
bd daemons restart 12345 --json
# Stop ALL daemons
bd daemons killall --json
bd daemons killall --force --json # Force kill if graceful fails
```
### View Daemon Logs
```bash
# View last 100 lines
bd daemons logs /path/to/workspace -n 100
# Follow mode (tail -f style)
bd daemons logs 12345 -f
# Debug sync issues
bd daemons logs . -n 500 | grep -i "export\|import\|sync"
```
**Common log patterns:**
- `[INFO] Auto-sync: export complete` - Successful JSONL export
- `[WARN] Git push failed: ...` - Push error (auto-retry)
- `[ERROR] Version mismatch` - Daemon/CLI version out of sync
## Version Management
**Automatic Version Checking (v0.16.0+):**
bd automatically handles daemon version mismatches:
- Version compatibility checked on every connection
- Old daemons automatically detected and restarted
- No manual intervention needed after upgrades
- Works with MCP server and CLI
**After upgrading bd:**
```bash
# 1. Check for mismatches
bd daemons health --json
# 2. Restart all daemons with new version
bd daemons killall
# 3. Next bd command auto-starts daemon with new version
bd ready
```
**Troubleshooting version mismatches:**
- Daemon won't stop: `bd daemons killall --force`
- Socket file stale: `rm .beads/bd.sock` (auto-cleans on next start)
- Multiple bd versions installed: `which bd` and `bd version`
## Event-Driven Daemon Mode (Experimental)
**NEW in v0.16+**: Event-driven mode replaces 5-second polling with instant reactivity.
### Benefits
- ⚡ **<500ms latency** (vs ~5000ms with polling)
- 🔋 **~60% less CPU usage** (no continuous polling)
- 🎯 **Instant sync** on mutations and file changes
- 🛡️ **Dropped events safety net** prevents data loss
### How It Works
**Architecture:**
```
FileWatcher (platform-native)
├─ .beads/issues.jsonl (file changes)
├─ .git/refs/heads (git updates)
└─ RPC mutations (create, update, close)
↓
Debouncer (500ms batch window)
↓
Export → Git Commit/Push
```
**Platform-native APIs:**
- Linux: `inotify`
- macOS: `FSEvents` (via kqueue)
- Windows: `ReadDirectoryChangesW`
**Mutation events** from RPC trigger immediate export
**Debouncer** batches rapid changes (500ms window) to avoid export storms
**Polling fallback** if fsnotify unavailable (network filesystems)
### Enabling Event-Driven Mode
**Opt-In (Phase 1):**
```bash
# Enable for single daemon
BEADS_DAEMON_MODE=events bd daemon start
# Set globally in shell profile
export BEADS_DAEMON_MODE=events
# Restart all daemons to apply
bd daemons killall
# Next bd command auto-starts with new mode
```
**Available modes:**
- `poll` (default) - Traditional 5-second polling, stable and battle-tested
- `events` - Event-driven mode, experimental but thoroughly tested
### Configuration
**Environment Variables:**
| Variable | Values | Default | Description |
|----------|--------|---------|-------------|
| `BEADS_DAEMON_MODE` | `poll`, `events` | `poll` | Daemon operation mode |
| `BEADS_WATCHER_FALLBACK` | `true`, `false` | `true` | Fall back to polling if fsnotify fails |
**Disable polling fallback (require fsnotify):**
```bash
# Fail if watcher unavailable (e.g., testing)
BEADS_WATCHER_FALLBACK=false BEADS_DAEMON_MODE=events bd daemon start
```
**Switch back to polling:**
```bash
# Explicitly use polling mode
BEADS_DAEMON_MODE=poll bd daemon start
# Or unset to use default
unset BEADS_DAEMON_MODE
bd daemons killall # Restart with default (poll) mode
```
### Troubleshooting Event-Driven Mode
**If watcher fails to start:**
```bash
# Check daemon logs for errors
bd daemons logs /path/to/workspace -n 100
# Common error patterns:
# - "File watcher unavailable: ..." - fsnotify init failed
# - "Falling back to polling" - watcher disabled, using polls
# - "Resource limit exceeded" - too many open files
```
**Common causes:**
1. **Network filesystem** (NFS, SMB) - fsnotify may not work
- Solution: Use polling mode or local filesystem
2. **Container environment** - may need privileged mode
- Solution: Add `--privileged` or specific capabilities
3. **Resource limits** - check `ulimit -n` (open file descriptors)
- Solution: Increase limit: `ulimit -n 4096`
4. **WSL/virtualization** - reduced fsnotify reliability
- Solution: Test in native environment or use polling
**Fallback behavior:**
If `BEADS_DAEMON_MODE=events` but watcher fails:
- Daemon automatically falls back to polling (if `BEADS_WATCHER_FALLBACK=true`)
- Warning logged: `File watcher unavailable, falling back to polling`
- All functionality works normally (just higher latency)
### Performance Comparison
| Metric | Polling Mode | Event-Driven Mode |
|--------|--------------|-------------------|
| Sync Latency | ~5000ms | <500ms |
| CPU Usage | ~2-3% (continuous) | ~0.5% (idle) |
| Memory | 30MB | 35MB (+5MB for watcher) |
| File Events | Polled every 5s | Instant detection |
| Git Updates | Polled every 5s | Instant detection |
**Future (Phase 2):** Event-driven mode will become default once proven stable in production.
## Auto-Start Behavior
**Default (v0.9.11+):** Daemon auto-starts on first bd command
```bash
# No manual start needed
bd ready # Daemon starts automatically if not running
# Check status
bd info --json | grep daemon_running
```
**Disable auto-start:**
```bash
# Require manual daemon start
export BEADS_AUTO_START_DAEMON=false
# Start manually
bd daemon start
```
**Auto-start with exponential backoff:**
- 1st attempt: immediate
- 2nd attempt: 100ms delay
- 3rd attempt: 200ms delay
- Max retries: 5
- Logs available: `bd daemons logs . -n 50`
## Daemon Configuration
**Environment Variables:**
| Variable | Values | Default | Description |
|----------|--------|---------|-------------|
| `BEADS_AUTO_START_DAEMON` | `true`, `false` | `true` | Auto-start daemon on commands |
| `BEADS_DAEMON_MODE` | `poll`, `events` | `poll` | Sync mode (polling vs events) |
| `BEADS_WATCHER_FALLBACK` | `true`, `false` | `true` | Fall back to poll if events fail |
| `BEADS_NO_DAEMON` | `true`, `false` | `false` | Disable daemon entirely (direct DB) |
**Example configurations:**
```bash
# Force direct mode (no daemon)
export BEADS_NO_DAEMON=true
# Event-driven with strict requirements
export BEADS_DAEMON_MODE=events
export BEADS_WATCHER_FALLBACK=false
# Disable auto-start (manual control)
export BEADS_AUTO_START_DAEMON=false
```
## Git Worktrees Warning
**⚠️ Important Limitation:** Daemon mode does NOT work correctly with `git worktree`.
**The Problem:**
- Git worktrees share the same `.git` directory and `.beads` database
- Daemon doesn't know which branch each worktree has checked out
- Can commit/push to wrong branch
**Solutions:**
1. **Use `--no-daemon` flag** (recommended):
```bash
bd --no-daemon ready
bd --no-daemon create "Fix bug" -p 1
```
2. **Disable via environment** (entire session):
```bash
export BEADS_NO_DAEMON=1
bd ready # All commands use direct mode
```
3. **Disable auto-start** (less safe):
```bash
export BEADS_AUTO_START_DAEMON=false
```
**Automatic detection:** bd detects worktrees and warns if daemon is active.
See [GIT_INTEGRATION.md](GIT_INTEGRATION.md) for more details.
## Exclusive Lock Protocol (Advanced)
**For external tools that need full database control** (e.g., CI/CD, deterministic execution).
When `.beads/.exclusive-lock` file exists:
- Daemon skips all operations for the locked database
- External tool has complete control over git sync and database
- Stale locks (dead process) auto-cleaned
**Lock file format (JSON):**
```json
{
"holder": "my-tool",
"pid": 12345,
"hostname": "build-server",
"started_at": "2025-11-08T08:00:00Z",
"version": "1.0.0"
}
```
**Quick example:**
```bash
# Create lock
echo '{"holder":"my-tool","pid":'$$',"hostname":"'$(hostname)'","started_at":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","version":"1.0.0"}' > .beads/.exclusive-lock
# Do work (daemon won't interfere)
bd create "My issue" -p 1
# Release lock
rm .beads/.exclusive-lock
```
**Use cases:**
- VibeCoder (deterministic execution)
- CI/CD pipelines (controlled sync timing)
- Testing frameworks (isolated test runs)
See [EXCLUSIVE_LOCK.md](../EXCLUSIVE_LOCK.md) for complete documentation.
## Common Daemon Issues
### Stale Sockets
**Symptoms:** `bd ready` shows "daemon not responding"
**Solutions:**
```bash
# Auto-cleanup on next command
bd daemons list # Removes stale sockets
# Manual cleanup
rm .beads/bd.sock
bd ready # Auto-starts fresh daemon
```
### Version Mismatch
**Symptoms:** `bd ready` shows "version mismatch" error
**Solutions:**
```bash
# Check versions
bd version
bd daemons health --json
# Restart all daemons
bd daemons killall
bd ready # Auto-starts with CLI version
```
### Daemon Won't Stop
**Symptoms:** `bd daemons stop` hangs or times out
**Solutions:**
```bash
# Force kill
bd daemons killall --force
# Nuclear option (all bd processes)
pkill -9 bd
# Clean up socket
rm .beads/bd.sock
```
### Memory Leaks
**Symptoms:** Daemon process grows to 100+ MB
**Solutions:**
```bash
# Check current memory usage
ps aux | grep "bd daemon"
# Restart daemon
bd daemons restart .
# Check logs for issues
bd daemons logs . -n 200 | grep -i "memory\|leak\|oom"
```
**Expected memory usage:**
- Baseline: ~30MB
- With watcher: ~35MB
- Per issue: ~500 bytes (10K issues = ~5MB)
## Multi-Workspace Best Practices
### When managing multiple projects:
```bash
# Check all daemons
bd daemons list --json
# Stop unused workspaces to free resources
bd daemons stop /path/to/old-project
# Health check before critical work
bd daemons health --json
# Clean restart after major upgrades
bd daemons killall
# Daemons restart on next command per workspace
```
### Resource limits:
- Each daemon: ~30-35MB memory
- 10 workspaces: ~300-350MB total
- CPU: <1% per daemon (idle), 2-3% (active sync)
- File descriptors: ~10 per daemon
### When to disable daemons:
- ✅ Git worktrees (use `--no-daemon`)
- ✅ Embedded/resource-constrained environments
- ✅ Testing/CI (deterministic execution)
- ✅ Offline work (no git push available)
## See Also
- [AGENTS.md](../AGENTS.md) - Main agent workflow guide
- [EXCLUSIVE_LOCK.md](../EXCLUSIVE_LOCK.md) - External tool integration
- [GIT_INTEGRATION.md](GIT_INTEGRATION.md) - Git workflow and merge strategies
- [commands/daemons.md](../commands/daemons.md) - Daemon command reference

527
docs/GIT_INTEGRATION.md Normal file
View File

@@ -0,0 +1,527 @@
# Git Integration Guide
**For:** AI agents and developers managing bd git workflows
**Version:** 0.21.0+
## Overview
bd integrates deeply with git for issue tracking synchronization. This guide covers merge conflict resolution, intelligent merge drivers, git worktrees, and protected branch workflows.
## Git Worktrees
**⚠️ Important Limitation:** Daemon mode does NOT work correctly with `git worktree`.
### The Problem
Git worktrees share the same `.git` directory and `.beads` database:
- All worktrees use the same `.beads/beads.db` file
- Daemon doesn't know which branch each worktree has checked out
- Can commit/push changes to the wrong branch
- Leads to confusion and incorrect git history
### What You Lose Without Daemon Mode
- **Auto-sync** - No automatic commit/push of changes (use `bd sync` manually)
- **MCP server** - beads-mcp requires daemon 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 (entire 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 worktrees and shows prominent warning if daemon mode is active. The `--no-daemon` mode works correctly 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.
## Handling Merge Conflicts
**With hash-based IDs (v0.20.1+), ID collisions are eliminated!** Different issues get different hash IDs, so most git merges succeed cleanly.
### When Conflicts Occur
Git conflicts in `.beads/beads.jsonl` happen when:
- **Same issue modified on both branches** (different timestamps/fields)
- This is a **same-issue update conflict**, not an ID collision
- Conflicts are rare in practice since hash IDs prevent structural collisions
### Automatic Detection
bd automatically detects conflict markers and shows clear resolution steps:
```bash
# bd import rejects files with conflict markers
bd import -i .beads/beads.jsonl
# Error: JSONL file contains git conflict markers
# Resolve with: git checkout --theirs .beads/beads.jsonl
# Validate for conflicts
bd validate --checks=conflicts
```
Conflict markers detected: `<<<<<<<`, `=======`, `>>>>>>>`
### Resolution Workflow
```bash
# After git merge creates conflict in .beads/beads.jsonl
# Option 1: Accept their version (remote)
git checkout --theirs .beads/beads.jsonl
bd import -i .beads/beads.jsonl
# Option 2: Keep our version (local)
git checkout --ours .beads/beads.jsonl
bd import -i .beads/beads.jsonl
# Option 3: Manual resolution in editor
# Edit .beads/beads.jsonl to remove conflict markers
bd import -i .beads/beads.jsonl
# Commit the merge
git add .beads/beads.jsonl
git commit
```
**Note:** `bd import` automatically handles updates - same ID with different content is a normal update operation. No special flags needed. If you accidentally modified the same issue in both branches, just pick whichever version is more complete.
## Intelligent Merge Driver (Auto-Configured)
**As of v0.21+**, bd automatically configures its own merge driver during `bd init`. This uses the beads-merge algorithm (by @neongreen, vendored into bd) to provide intelligent JSONL merging.
### What It Does
- **Field-level 3-way merging** (not line-by-line)
- **Matches issues by identity** (id + created_at + created_by)
- **Smart field merging:**
- Timestamps → max value
- Dependencies → union
- Status/priority → 3-way merge
- **Conflict markers** only for unresolvable conflicts
- **Auto-configured** during `bd init` (both interactive and `--quiet` modes)
### Auto-Configuration
**Happens automatically during `bd init`:**
```bash
# These are configured automatically:
git config merge.beads.driver "bd merge %A %O %L %R"
git config merge.beads.name "bd JSONL merge driver"
# .gitattributes entry added:
# .beads/beads.jsonl merge=beads
```
### Manual Setup
**If you skipped merge driver with `--skip-merge-driver`:**
```bash
git config merge.beads.driver "bd merge %A %O %L %R"
git config merge.beads.name "bd JSONL merge driver"
echo ".beads/beads.jsonl merge=beads" >> .gitattributes
```
### How It Works
During `git merge`, beads-merge:
1. Parses JSONL from all 3 versions (base, ours, theirs)
2. Matches issues by identity (id + created_at + created_by)
3. Merges fields intelligently per issue
4. Outputs merged JSONL or conflict markers
**Benefits:**
- Prevents spurious conflicts from line renumbering
- Handles timestamp updates gracefully
- Merges dependency/label changes intelligently
- Only conflicts on true semantic conflicts
### Alternative: Standalone beads-merge Binary
**If you prefer the standalone binary (same algorithm):**
```bash
# Install (requires Go 1.21+)
git clone https://github.com/neongreen/mono.git
cd mono/beads-merge
go install
# Configure Git merge driver
git config merge.beads.name "JSONL merge driver for beads"
git config merge.beads.driver "beads-merge %A %O %A %B"
```
### Jujutsu Integration
**For Jujutsu users**, add to `~/.jjconfig.toml`:
```toml
[merge-tools.beads-merge]
program = "beads-merge"
merge-args = ["$output", "$base", "$left", "$right"]
merge-conflict-exit-codes = [1]
```
Then resolve with:
```bash
jj resolve --tool=beads-merge
```
## Protected Branch Workflows
**If your repository uses protected branches** (GitHub, GitLab, etc.), bd can commit to a separate branch instead of `main`:
### Configuration
```bash
# Initialize with separate sync branch
bd init --branch beads-metadata
# Or configure existing setup
bd config set sync.branch beads-metadata
```
### How It Works
- Beads commits issue updates to `beads-metadata` instead of `main`
- Uses git worktrees (lightweight checkouts) in `.git/beads-worktrees/`
- Your main working directory is never affected
- Periodically merge `beads-metadata` back to `main` via pull request
### Daily Workflow (Unchanged for Agents)
```bash
# Agents work normally - no changes needed!
bd create "Fix authentication" -t bug -p 1
bd update bd-a1b2 --status in_progress
bd close bd-a1b2 "Fixed"
```
All changes automatically commit to `beads-metadata` branch (if daemon is running with `--auto-commit`).
### Merging to Main (Humans)
```bash
# Check what's changed
bd sync --status
# Option 1: Create pull request
git push origin beads-metadata
# Then create PR on GitHub/GitLab
# Option 2: Direct merge (if allowed)
bd sync --merge
```
### Benefits
- ✅ Works with protected `main` branches
- ✅ No disruption to agent workflows
- ✅ Platform-agnostic (works on any git platform)
- ✅ Backward compatible (opt-in via config)
See [PROTECTED_BRANCHES.md](PROTECTED_BRANCHES.md) for complete setup guide, troubleshooting, and examples.
## Git Hooks Integration
**STRONGLY RECOMMENDED:** Install git hooks for automatic sync and consistency.
### Installation
```bash
# One-time setup in each beads workspace
./examples/git-hooks/install.sh
```
### What Gets Installed
**pre-commit hook:**
- Flushes pending changes immediately before commit
- Bypasses 30-second debounce
- Guarantees JSONL is current
**post-merge hook:**
- Imports updated JSONL after pull/merge
- Guarantees database sync after remote changes
**pre-push hook:**
- Exports database to JSONL before push
- Prevents stale JSONL from reaching remote
- **Critical for multi-workspace consistency**
### Why Hooks Matter
**Without pre-push hook:**
- Database changes committed locally
- Stale JSONL pushed to remote
- Other workspaces diverge from truth
**With pre-push hook:**
- JSONL always reflects database state
- All workspaces stay synchronized
- No manual `bd sync` needed
See [examples/git-hooks/README.md](../examples/git-hooks/README.md) for details.
## Multi-Workspace Sync Strategies
### Centralized Repository Pattern
```
┌──────────────┐
│ Developer A │────┐
│ (Workspace) │ │
└──────────────┘ │
▼
┌──────────────┐ ┌─────────────────┐
│ Developer B │─▶│ Central Repo │
│ (Workspace) │ │ (.beads/*.jsonl)│
└──────────────┘ └─────────────────┘
▲
┌──────────────┐ │
│ CI/CD │────┘
│ (Workspace) │
└──────────────┘
```
**Best for:**
- Teams working on shared repository
- CI/CD integration
- Multi-agent workflows
**Key points:**
- Each workspace has its own daemon
- Git is the source of truth
- Auto-sync keeps workspaces consistent
### Fork-Based Pattern
```
┌──────────────┐ ┌─────────────────┐
│ OSS Contrib │─────▶│ Planning Repo │
│ (Fork) │ │ (.beads/*.jsonl)│
└──────────────┘ └─────────────────┘
│
│ PR
▼
┌─────────────────┐
│ Upstream Repo │
│ (no .beads/) │
└─────────────────┘
```
**Best for:**
- Open source contributors
- Solo developers
- Private task tracking on public repos
**Setup:**
```bash
bd init --contributor # Interactive wizard
```
See [MULTI_REPO_MIGRATION.md](MULTI_REPO_MIGRATION.md) for complete guide.
### Team Branch Pattern
```
┌──────────────┐
│ Team Member │────┐
│ (main) │ │
└──────────────┘ │
▼
┌──────────────┐ ┌─────────────────┐
│ Team Member │─▶│ Shared Repo │
│ (main) │ │ (beads-metadata)│
└──────────────┘ └─────────────────┘
```
**Best for:**
- Teams on protected branches
- Managed git workflows
- Review-before-merge policies
**Setup:**
```bash
bd init --team # Interactive wizard
```
See [MULTI_REPO_MIGRATION.md](MULTI_REPO_MIGRATION.md) for complete guide.
## Sync Timing and Control
### Automatic Sync (Default)
**With daemon running:**
- Export to JSONL: 30-second debounce after changes
- Import from JSONL: when file is newer than DB
- Commit/push: configurable via `--auto-commit` / `--auto-push`
**30-second debounce provides transaction window:**
- Multiple changes within 30s get batched
- Single JSONL export/commit for the batch
- Prevents commit spam
### Manual Sync
```bash
# Force immediate sync (bypass debounce)
bd sync
# What it does:
# 1. Export pending changes to JSONL
# 2. Commit to git
# 3. Pull from remote
# 4. Import any updates
# 5. Push to remote
```
**ALWAYS run `bd sync` at end of agent sessions** to ensure changes are committed/pushed.
### Disable Automatic Sync
```bash
# Disable auto-flush (no export until manual sync)
bd --no-auto-flush ready
# Disable auto-import (no import on file changes)
bd --no-auto-import ready
# Disable both (manual sync only)
export BEADS_NO_DAEMON=1 # Direct mode
```
## Git Configuration Best Practices
### Recommended .gitignore
```
# bd database (not tracked - JSONL is source of truth)
.beads/beads.db
.beads/beads.db-*
.beads/bd.sock
.beads/bd.pipe
# bd daemon state
.beads/.exclusive-lock
# Git worktrees (if using protected branches)
.git/beads-worktrees/
```
### Recommended .gitattributes
```
# Intelligent merge driver for JSONL (auto-configured by bd init)
.beads/beads.jsonl merge=beads
# Treat JSONL as text for diffs
.beads/*.jsonl text diff
```
### Git LFS Considerations
**Do NOT use Git LFS for `.beads/beads.jsonl`:**
- JSONL needs intelligent merge (doesn't work with LFS)
- File size stays reasonable (<1MB per 10K issues)
- Text diffs are valuable for review
## Troubleshooting Git Issues
### Issue: "JSONL file is ahead of database"
**Symptoms:**
```
WARN Database timestamp older than JSONL, importing...
```
**Solutions:**
```bash
# Normal after git pull - auto-import handles it
# If stuck, force import:
bd import -i .beads/beads.jsonl
```
### Issue: "Database is ahead of JSONL"
**Symptoms:**
```
WARN JSONL timestamp older than database, exporting...
```
**Solutions:**
```bash
# Normal after local changes - auto-export handles it
# If stuck, force export:
bd sync
```
### Issue: Merge conflicts every time
**Symptoms:**
- Git merge always creates conflicts in `.beads/beads.jsonl`
- Merge driver not being used
**Solutions:**
```bash
# Check merge driver configured
git config merge.beads.driver
# Reinstall if missing
bd init --skip-db # Only reconfigure git, don't touch database
# Verify .gitattributes
grep "beads.jsonl" .gitattributes
# Expected: .beads/beads.jsonl merge=beads
```
### Issue: Changes not syncing to other workspaces
**Symptoms:**
- Agent A creates issue
- Agent B doesn't see it after `git pull`
**Solutions:**
```bash
# Agent A: Ensure changes were pushed
bd sync
git push
# Agent B: Force import
git pull
bd import -i .beads/beads.jsonl
# Check git hooks installed (prevent future issues)
./examples/git-hooks/install.sh
```
## See Also
- [AGENTS.md](../AGENTS.md) - Main agent workflow guide
- [DAEMON.md](DAEMON.md) - Daemon management and configuration
- [PROTECTED_BRANCHES.md](PROTECTED_BRANCHES.md) - Protected branch workflows
- [MULTI_REPO_MIGRATION.md](MULTI_REPO_MIGRATION.md) - Multi-repo patterns
- [examples/git-hooks/README.md](../examples/git-hooks/README.md) - Git hooks integration