Refactor AGENTS.md: extract supplemental docs
- 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
596
AGENTS.md
596
AGENTS.md
@@ -142,337 +142,55 @@ If you must use separate MCP servers:
|
|||||||
|
|
||||||
### CLI Quick Reference
|
### CLI Quick Reference
|
||||||
|
|
||||||
If you're not using the MCP server, here are the CLI commands:
|
**Essential commands for AI agents:**
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Check database path and daemon status
|
# Find work
|
||||||
bd info --json
|
bd ready --json # Unblocked issues
|
||||||
|
bd stale --days 30 --json # Forgotten issues
|
||||||
|
|
||||||
# Find ready work (no blockers)
|
# Create and manage issues
|
||||||
bd ready --json
|
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)
|
# Search and filter
|
||||||
bd stale --days 30 --json # Default: 30 days
|
bd list --status open --priority 1 --json
|
||||||
bd stale --days 90 --status in_progress --json # Filter by status
|
bd list --label-any urgent,critical --json
|
||||||
bd stale --limit 20 --json # Limit results
|
bd show <id> --json
|
||||||
|
|
||||||
# Create new issue
|
# Sync (CRITICAL at end of session!)
|
||||||
# IMPORTANT: Always quote titles and descriptions with double quotes
|
bd sync # Force immediate export/commit/push
|
||||||
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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**Migration safety:** The system verifies data integrity invariants after migrations:
|
**For comprehensive CLI documentation**, see [docs/CLI_REFERENCE.md](docs/CLI_REFERENCE.md).
|
||||||
|
|
||||||
- **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).
|
|
||||||
|
|
||||||
### Managing Daemons
|
### 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
|
```bash
|
||||||
# List all running daemons
|
bd daemons list --json # List all running daemons
|
||||||
bd daemons list --json
|
bd daemons health --json # Check for version mismatches
|
||||||
|
bd daemons logs . -n 100 # View daemon logs
|
||||||
# Check health (version mismatches, stale sockets)
|
bd daemons killall --json # Restart all daemons
|
||||||
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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**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
|
**For complete daemon management**, see [docs/DAEMON.md](docs/DAEMON.md).
|
||||||
- **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.
|
|
||||||
|
|
||||||
### Web Interface (Monitor)
|
### 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 human visualization:
|
||||||
|
|
||||||
bd includes a built-in web interface for real-time issue monitoring:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
bd monitor # Start on localhost:8080
|
bd monitor # Start on localhost:8080
|
||||||
bd monitor --port 3000 # Custom port
|
bd monitor --port 3000 # Custom port
|
||||||
bd monitor --host 0.0.0.0 --port 80 # Public access
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**Features:**
|
**AI agents**: Continue using CLI with `--json` flags. The monitor is for human supervision only.
|
||||||
|
|
||||||
- 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.
|
|
||||||
|
|
||||||
### Workflow
|
### Workflow
|
||||||
|
|
||||||
@@ -485,6 +203,50 @@ bd daemons killall # Restart with default (poll) mode
|
|||||||
5. **Complete**: `bd close <id> --reason "Implemented"`
|
5. **Complete**: `bd close <id> --reason "Implemented"`
|
||||||
6. **Sync at end of session**: `bd sync` (see "Agent Session Workflow" below)
|
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
|
### Issue Types
|
||||||
|
|
||||||
- `bug` - Something broken that needs fixing
|
- `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.
|
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
|
**Protected branches**: Use `bd init --branch beads-metadata` to commit to separate branch. See [docs/PROTECTED_BRANCHES.md](docs/PROTECTED_BRANCHES.md).
|
||||||
# Initialize with separate sync branch
|
|
||||||
bd init --branch beads-metadata
|
|
||||||
|
|
||||||
# Or configure existing setup
|
**Git worktrees**: Daemon mode NOT supported. Use `bd --no-daemon` for all commands. See [docs/GIT_INTEGRATION.md](docs/GIT_INTEGRATION.md).
|
||||||
bd config set sync.branch beads-metadata
|
|
||||||
```
|
|
||||||
|
|
||||||
**How it works:**
|
**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).
|
||||||
|
|
||||||
- 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.**
|
|
||||||
|
|
||||||
### Landing the Plane
|
### 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.
|
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
|
## 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
|
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
|
## Common Tasks
|
||||||
|
|
||||||
|
|||||||
464
docs/CLI_REFERENCE.md
Normal file
464
docs/CLI_REFERENCE.md
Normal 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
495
docs/DAEMON.md
Normal 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
527
docs/GIT_INTEGRATION.md
Normal 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
|
||||||
Reference in New Issue
Block a user