A distributed, git-backed graph issue tracker specifically designed for AI agents to manage complex task dependencies and project state.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install beads
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install beads using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is beads?
Beads is a specialized issue tracking system built for the era of AI-driven development. Unlike traditional trackers that rely on centralized databases or messy markdown files, this tool stores a dependency-aware task graph as JSONL files directly within your repository's .beads directory. This ensures that task state is version-controlled alongside your code, making it a vital component for Openclaw Skills that require robust project management.
By focusing on machine-readable outputs and non-interactive workflows, it allows AI agents to autonomously identify unblocked work, track progress, and manage complex hierarchies of tasks without human intervention. It effectively replaces static planning documents with a dynamic, queryable graph.
beads Use Cases
- Managing multi-step AI agent workflows with complex inter-task dependencies.
- Replacing flat markdown task lists with version-controlled, hierarchical issue graphs.
- Coordinating work between multiple AI agents or human-agent teams within a shared git repository.
- Automated tracking of bugs, features, and epics discovered during the autonomous development process.
How beads Works
- Initialize the system using
bd initto create the local graph storage and optional git hooks. - Create tasks or epics with assigned priorities and dependencies to define the project scope.
- Query the work queue using
bd ready --jsonto identify tasks that are currently unblocked and ready for execution. - Update task status to 'in_progress' and assign it to an agent to claim the work.
- Complete the work and close the issue, which automatically unblocks downstream dependencies in the graph.
- Synchronize changes across the distributed team using
bd syncto push and pull task updates via git.
beads Setup
Install the beads CLI via your preferred package manager:
# Via Homebrew
brew install beads
# Via NPM
npm install -g @beads/bd
Initialize your project:
# For AI agents (non-interactive)
bd init --quiet
beads Data Schema & Taxonomy
Beads organizes data locally in a .beads/ directory using the JSONL format for easy git merging and machine parsing.
| Component | Description |
|---|---|
| .beads/ | Root directory for all task and metadata storage. |
| Task IDs | Hierarchical format (e.g., bd-a3f8 for epics, bd-a3f8.1 for subtasks). |
| JSONL | Each line represents an event or state change in the issue life cycle. |
| Statuses | open, in_progress, blocked, closed. |
| Priorities | Numeric scale from 0 (Critical) to 3 (Low). |
beads Advanced Features
- Hierarchical ID system supporting up to 3 levels of task nesting (Epics -> Tasks -> Subtasks).
- Multi-agent coordination via explicit assignee tracking and unblocked work queries for Openclaw Skills.
- Git-integrated synchronization with auto-debounce and hook-based automation.
- Complex dependency mapping including 'blocks', 'related', 'parent', and 'discovered-from' relationship types.
- Administrative compaction tools to maintain database health over long-running projects.
SKILL.md
Loading
Related Openclaw Skills
ContextClaw
ContextClaw is a comprehensive session management and cleanup utility designed to optimize storage and analyze token consumption for AI agents.
ActivityClaw Plugin
A real-time activity monitoring plugin for tracking file operations, command executions, and web searches performed by your AI agent.
HelpScout CLI (hs)
A powerful command-line interface for managing HelpScout Inbox and Docs APIs, enabling full CRUD operations for conversations, customers, and knowledge base articles.
ghapp
A CLI utility that grants AI agents and automations their own GitHub App identity for seamless, bot-attributed git and gh operations.
RNWY Agent Registry — A2A Card Lookup
A verification and discovery engine for AI agents that provides live A2A agent cards and trust scores for over 40,000 entities.
Brave Search
A high-performance tool for headless web search and markdown content extraction using the Brave Search API.
Featured*
