Git-backed issue tracker for AI agents. Use when managing tasks, dependencies, or multi-step work. Triggers on task tracking, issue management, dependency graphs, ready work queues, or mentions of "be
Real data. Real impact.
Growing
Developers
Per week
Open source
Skills give you superpowers. Install in 30 seconds.
Distributed, git-backed graph issue tracker for AI agents. Replaces markdown plans with a dependency-aware task graph stored as JSONL in
.beads/# Initialize (non-interactive for agents) bd init --quietCheck ready work
bd ready --json
Create a task
bd create "Complete task X" -p 1 --json
View task
bd show bd-a1b2 --json
bd ready --jsonbd update <id> --status in_progressbd close <id> --reason "Done"bd sync--jsonbd editbd updatebd update <id> --title "New title" --description "New desc"bd syncbd init --quiet # Non-interactive, auto-installs hooks bd init --prefix myproj # Custom ID prefix bd init --stealth # Local only, don't commit .beads/ bd init --contributor # Fork workflow (separate planning repo)
bd create "Title" -p 1 --json # Priority 1 (0=critical, 3=low) bd create "Title" -t epic -p 0 --json # Create epic bd create "Subtask" -p 1 --json # Under epic: bd-a3f8.1, .2, .3 bd create "Found issue" --deps discovered-from:bd-a1b2 --json
Types:
taskbugfeatureepic03bd ready --json # Unblocked tasks (the work queue) bd ready --priority 0 --json # Only P0s bd ready --assignee agent-1 --json # Assigned to specific agentbd list --json # All issues bd list --status open --json # Open issues bd list --priority 1 --json # P1 issues
bd show bd-a1b2 --json # Issue details + audit trail bd blocked --json # Issues waiting on dependencies bd stats --json # Statistics
bd update bd-a1b2 --status in_progress --json bd update bd-a1b2 --title "New title" --json bd update bd-a1b2 --description "Details" --json bd update bd-a1b2 --priority 0 --json bd update bd-a1b2 --assignee agent-1 --json bd update bd-a1b2 --design "Design notes" --json bd update bd-a1b2 --notes "Additional notes" --json
Status values:
openin_progressblockedclosedbd close bd-a1b2 --reason "Completed" --json bd close bd-a1b2 bd-b2c3 --reason "Batch close" --json
bd dep add bd-child bd-parent # child blocked by parent bd dep add bd-a1b2 bd-b2c3 --type related # Related link bd dep add bd-a1b2 bd-epic --type parent # Parent-childbd dep tree bd-a1b2 # Visualize dependency tree bd dep remove bd-child bd-parent # Remove dependency bd dep cycles # Detect circular deps
Dependency types:
blocksrelatedparentdiscovered-frombd sync # Export → commit → pull → import → push bd hooks install # Install git hooks for auto-sync
The daemon auto-syncs with 30s debounce. Use
bd syncbd admin compact --dry-run --json # Preview compaction bd admin compact --days 90 # Compact issues closed >90 days bd doctor # Check database health
bd create "Project Alpha" -t epic -p 1 --json # Returns: bd-a3f8 bd create "Phase 1" -p 1 --json # Returns: bd-a3f8.1 bd create "Research" -p 1 --json # Returns: bd-a3f8.2 bd create "Review" -p 1 --json # Returns: bd-a3f8.3
Up to 3 levels:
bd-a3f8bd-a3f8.1bd-a3f8.1.1# Agent claims work bd update bd-a1b2 --status in_progress --assignee agent-1 --jsonQuery assigned work
bd ready --assignee agent-1 --json
Track discovered work
bd create "Found issue" --deps discovered-from:bd-a1b2 --json
For git-tracked projects, include issue ID in commit messages for traceability:
git commit -m "Complete research phase (bd-a1b2)"
Before ending a session:
bd sync # Flush all changes bd ready --json # Show next work for handoff
No automatic installation available. Please visit the source repository for installation instructions.
View Installation Instructions
1,500+ AI skills, agents & workflows. Install in 30 seconds. Part of the Torly.ai family.
© 2026 Torly.ai. All rights reserved.