beads

What This Skill Does

Beads is a powerful, git-backed graph issue tracker designed specifically for autonomous AI agents. Unlike traditional project management tools that rely on isolated databases or messy markdown lists, Beads treats your project roadmap as a living, dependency-aware graph stored directly within your repository under .beads/. By version-controlling your task state, it allows agents to maintain context, handle complex multi-step workflows, and ensure that progress is tracked transparently within the same environment as the code itself. The skill provides a CLI-first interface optimized for machine-readable output, ensuring that agents can parse, update, and manage their own work queues with high reliability.

Installation

To add the Beads skill to your OpenClaw environment, execute the following command in your terminal:

clawhub install openclaw/skills/skills/rnijhara/beads

Once installed, you should navigate to your project root and initialize the workspace to establish the tracking infrastructure:

bd init --quiet

Use Cases

• Complex Software Development: Manage intricate dependency graphs where task A must finish before task B can begin.
• Autonomous Research: Track iterative research steps where each 'bead' represents a completed discovery or refined hypothesis.
• Batch Task Management: Handle large-scale refactoring or multi-file migrations by creating a hierarchy of parent/child issues.
• Multi-Agent Coordination: Allow multiple AI agents to check the current 'ready' queue and pick up unblocked tasks without overlapping.

Example Prompts

1. "I'm ready to start working on the project. Please check the beads ready queue, find the highest priority task, and set it to in_progress."
2. "I've completed the authentication refactor. Please close issue bd-a1b2 with the reason 'Refactor complete' and show me the next available task."
3. "Create a new feature issue for the API endpoint implementation and make it a subtask of our current development epic."

Tips & Limitations

• Always JSON: Never interact with the CLI without the --json flag. This prevents the agent from parsing terminal escape codes or human-formatted tables, which often lead to execution errors.
• Avoid bd edit: This command is strictly forbidden as it expects a human-interactive text editor (like vim or nano). Always use bd update to modify issue properties.
• Sync Regularly: Ensure the agent runs bd sync as its final step before terminating a session; this ensures that all task transitions are committed to git.
• Stealth Mode: If you are running experiments, use bd init --stealth to keep your issue tracking data local and prevent cluttering your repository's commit history.