beadsGit-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 "beads" / "bd" CLI.
Install via ClawdBot CLI:
clawdbot install rnijhara/beadsDistributed, 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 --quiet
# Check ready work
bd ready --json
# Create a task
bd create "Complete task X" -p 1 --json
# View task
bd show bd-a1b2 --jsonbd ready --json — Find unblocked workbd update --status in_progress — Claim taskbd close --reason "Done" — Complete taskbd sync — Force sync before ending session--json for machine-readable outputbd edit — opens $EDITOR, unusable by agentsbd update instead: bd update --title "New title" --description "New desc" bd sync at end of session to flush changes to gitbd 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 --jsonTypes: task, bug, feature, epic
Priorities: 0 (P0/critical) to 3 (P3/low)
bd ready --json # Unblocked tasks (the work queue)
bd ready --priority 0 --json # Only P0s
bd ready --assignee agent-1 --json # Assigned to specific agent
bd 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 # Statisticsbd 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" --jsonStatus values: open, in_progress, blocked, closed
bd close bd-a1b2 --reason "Completed" --json
bd close bd-a1b2 bd-b2c3 --reason "Batch close" --jsonbd 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-child
bd dep tree bd-a1b2 # Visualize dependency tree
bd dep remove bd-child bd-parent # Remove dependency
bd dep cycles # Detect circular depsDependency types: blocks (default), related, parent, discovered-from
bd sync # Export → commit → pull → import → push
bd hooks install # Install git hooks for auto-syncThe daemon auto-syncs with 30s debounce. Use bd sync to force immediate sync.
bd admin compact --dry-run --json # Preview compaction
bd admin compact --days 90 # Compact issues closed >90 days
bd doctor # Check database healthbd 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.3Up to 3 levels: bd-a3f8 → bd-a3f8.1 → bd-a3f8.1.1
# Agent claims work
bd update bd-a1b2 --status in_progress --assignee agent-1 --json
# Query assigned work
bd ready --assignee agent-1 --json
# Track discovered work
bd create "Found issue" --deps discovered-from:bd-a1b2 --jsonFor 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 handoffGenerated Mar 1, 2026
An AI agent uses beads to manage its own tasks, dependencies, and multi-step workflows. It initializes a beads repository, queries for ready work, updates task statuses, and syncs changes at the end of each session, ensuring a structured, git-backed record of progress.
A distributed software team employs beads to track bugs, features, and epics across multiple repositories. Developers use it to assign tasks, visualize dependency graphs, and batch close issues, with automatic git syncing maintaining consistency in a collaborative environment.
Researchers utilize beads to organize complex projects into hierarchical epics and subtasks. They track dependencies between experiments, log discovered issues, and use priority levels to focus on critical work, with JSON output enabling data analysis and reporting.
DevOps engineers integrate beads into CI/CD pipelines to manage deployment tasks and incident responses. They create issues for pipeline failures, set dependencies on infrastructure changes, and use the ready queue to prioritize fixes, ensuring traceability through git commits.
A media team uses beads to coordinate content creation, from ideation to publication. They create epics for campaigns, subtasks for writing and editing, and track dependencies on asset availability, with multi-agent features allowing assignment to different team members.
Offer beads as a free, open-source tool for individual users and small teams, while providing paid support, training, and customization services for enterprises. Revenue is generated through consulting contracts and priority assistance for integration with existing systems.
Host beads as a cloud-based service with enhanced collaboration features, such as real-time syncing, advanced analytics, and integrations with popular project management tools. Charge teams based on the number of users or projects, with tiered pricing for additional storage and features.
License beads to large organizations for on-premises deployment, offering enhanced security, compliance features, and dedicated support. Revenue comes from one-time licensing fees or annual maintenance contracts, with customization options for specific industry needs like healthcare or finance.
💬 Integration Tip
Always use the --json flag for machine-readable output and run bd sync at the end of each session to ensure changes are committed to git, avoiding data loss.
Captures learnings, errors, and corrections to enable continuous improvement. Use when: (1) A command or operation fails unexpectedly, (2) User corrects Clau...
Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
Search and analyze your own session logs (older/parent conversations) using jq.
Typed knowledge graph for structured agent memory and composable skills. Use when creating/querying entities (Person, Project, Task, Event, Document), linking related objects, enforcing constraints, planning multi-step actions as graph transformations, or when skills need to share state. Trigger on "remember", "what do I know about", "link X to Y", "show dependencies", entity CRUD, or cross-skill data access.
Ultimate AI agent memory system for Cursor, Claude, ChatGPT & Copilot. WAL protocol + vector search + git-notes + cloud backup. Never lose context again. Vibe-coding ready.
Headless browser automation CLI optimized for AI agents with accessibility tree snapshots and ref-based element selection