- name
- beads
- description
- Guide for using Beads (bd) - A memory upgrade and task management tool for AI agents.
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/bdHomebrew
brew install steveyegge/beads/bdGo
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-a1b24. 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-id6. 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
bdso you don't have to hold everything in your immediate context window. - Resilience: If your session crashes or restarts, run
bd readyto see exactly where you left off. - Collaboration: If the user is also using
bd, you can see their tasks and status updates instantly.