Beads (bd) Skill

Beads is a distributed task management system designed specifically for AI agents. It effectively gives you a "long-term memory" and a structured way to plan, track, and execute complex workflows without losing context. It uses Git as its database, meaning tasks are versioned, branched, and merged alongside code.

📦 Installation

If bd is not found, you can install it using one of the following methods for the user (ask for permission if unsure):

npm (Recommended)

npm install -g @beads/bd

Homebrew

brew install steveyegge/beads/bd

Go

go install github.com/steveyegge/beads/cmd/bd@latest

🚀 Initialization

Before using Beads in a repository, you must initialize it.

Initialize:
```
bd init
```
Use bd init --stealth if you want to use Beads locally without committing the .beads directory to the remote repo (good for personal tracking).
Install Hooks (CRITICAL for Agents):
```
bd hooks install
```
This ensures that your changes are automatically synced and consistency is maintained between the JSONL database and Git.

🤖 Agent Workflow (CRITICAL RULES)

As an AI agent, you must follow these rules strictly to interact with bd correctly.

1. NO Interactive Editors

NEVER use bd edit. It opens a text editor (vim/nano) which you cannot interact with. ALWAYS use bd update with specific flags.

2. ALWAYS Sync

At the end of a session or after making a batch of changes, ALWAYS run:

bd sync

This forces an immediate flush of the 30-second debounce buffer, commits changes, pulls from remote, imports updates, and pushes to remote. Without this, your changes might be lost or become stale.

3. Creating Tasks

Create a new task with a title and priority (-p).

Priority 0: High
Priority 1: Medium
Priority 2: Low

bd create "Refactor login component" -p 1
# Output: Created task bd-a1b2

4. Updating Tasks

Use flags to update specific fields.

# Update description
bd update bd-a1b2 --description "Refactoring the login component to use hooks."

# Update title
bd update bd-a1b2 --title "Refactor Login to Functional Component"

# Update status
bd update bd-a1b2 --status in_progress

# Update design notes
bd update bd-a1b2 --design "Using React.useState and React.useEffect"

# Update acceptance criteria
bd update bd-a1b2 --acceptance "1. User can login\n2. User can logout"

5. Managing Dependencies

Structure your work hierarchically.

# Add a child task to a parent
bd dep add bd-child-id bd-parent-id

6. Closing Tasks

Close a task when it's done.

bd close bd-a1b2 --reason "Completed"

7. Listing Tasks

View current tasks to understand your state.

bd ready   # Show actionable tasks (unblocked, open)
bd show bd-a1b2 # Show details of a specific task

📝 Example Session

# 1. Start a new feature
bd create "Implement Dark Mode" -p 0
# > Created bd-d4rks

# 2. Break it down
bd create "Add theme context" -p 1
# > Created bd-ctx1
bd dep add bd-ctx1 bd-d4rks

bd create "Add toggle button" -p 1
# > Created bd-t0g1
bd dep add bd-t0g1 bd-d4rks

# 3. Start working
bd update bd-ctx1 --status in_progress

# ... (Do the coding work) ...

# 4. Mark as done
bd close bd-ctx1 --reason "Implemented"

# 5. SYNC YOUR WORK
bd sync

💡 Why use Beads?

Context Preservation: Offload your planning to bd so you don't have to hold everything in your immediate context window.
Resilience: If your session crashes or restarts, run bd ready to see exactly where you left off.
Collaboration: If the user is also using bd, you can see their tasks and status updates instantly.