This guide explains how AI coding agents use Beads to manage tasks, track dependencies, and handle long-horizon work without losing context.
Why agents need Beads AI coding agents face unique challenges:
Context loss : Session boundaries and token limits cause agents to forget previous workNo structured planning : Markdown TODO lists are unstructured and hard to queryNo dependency tracking : Can’t determine what’s ready to work onMerge conflicts : Multiple agents or sessions create conflicting task lists
Beads solves these problems with:
Persistent memory : Dolt-backed database survives sessions and account rotationsDependency tracking : Automatically detects ready work with bd readyZero conflicts : Hash-based IDs prevent merge collisionsStructured queries : JSON output for programmatic use
Basic agent workflow A typical agent session follows this pattern:
Check for ready work
Start by finding unblocked tasks: This returns issues with no open blockers, sorted by priority.
[ { "id" : "bd-a3f8" , "title" : "Add authentication" , "priority" : 0 , "status" : "open" , "created_at" : "2026-03-04T10:00:00Z" } ]
Claim the task atomically
Use --claim to atomically set assignee and status: bd update bd-a3f8 --claim --json
This prevents multiple agents from working on the same task. The --claim flag sets assignee=<your-username> and status=in_progress in a single atomic operation.
Work on the task
Implement, test, and document the feature. As you discover new work, create linked issues: echo 'Found a bug in validation logic' | bd create "Fix validation" --description=- -p 1 --deps discovered-from:bd-a3f8 --json
The discovered-from dependency links the new issue to the parent task.
Complete the task
When finished, close the issue: bd close bd-a3f8 --reason "Completed" --json
Any dependencies on this task are now unblocked. Discovered work pattern When agents discover new work during implementation, they should link it to the parent:
# Discovered a bug while implementing authentication bd create "Fix password hashing" -p 1 --deps discovered-from:bd-a3f8 # Discovered missing tests bd create "Add auth integration tests" -t task -p 2 --deps discovered-from:bd-a3f8 # Discovered documentation gap bd create "Document auth setup" -t task -p 3 --deps discovered-from:bd-a3f8
This creates a discoverable audit trail showing what work was found during which task.
Session completion protocol When ending a work session, agents should:
File remaining work
Create issues for anything that needs follow-up: bd create "Add rate limiting to auth" -t feature -p 2 --json bd create "Fix failing CI tests" -t bug -p 0 --json
Update issue status
Close finished work, update in-progress items: bd close bd-a3f8 bd-b7c2 --reason "Completed" bd update bd-d4f9 --status in_progress --notes "Partially complete, needs tests"
Push to remote
Ensure all changes are pushed: git pull --rebase git push git status # Verify "up to date with origin"
Never end a session without pushing. Unpushed work causes conflicts for other agents.
Provide handoff context
Choose next work and provide context: bd ready --json bd show bd-next --json
Return a summary and prompt for the next session:
“Continue work on bd-d4f9: Add rate limiting. Authentication is complete (bd-a3f8), need to implement rate limiting middleware and tests.”
Using bd prime for context The bd prime command generates a context dump for agents:
This outputs:
Ready work (unblocked tasks)
Current work (in-progress issues)
Recent activity
Project statistics
Stored memories (from bd remember)
Agents can use this at session start to understand project state.
BEADS PRIME CONTEXT =================== READY WORK (3 issues) - bd-a3f8: Add authentication [P0] - bd-b7c2: Fix validation bug [P1] - bd-d4f9: Document API endpoints [P2] CURRENT WORK (1 issue) - bd-f6k1: Implement rate limiting [P1] (assigned to agent-1) RECENT ACTIVITY - bd-c5m8 closed: "Add user registration" (2h ago) - bd-d4f9 created: "Document API endpoints" (3h ago) PROJECT STATS - Open: 12 issues - Blocked: 4 issues - In Progress: 1 issue MEMORIES - api-testing: "Use pytest-asyncio for async tests, not unittest" - database-migrations: "Run migrations in transaction for rollback on failure"
Non-interactive commands only Never use bd edit - it opens an interactive editor that agents cannot use.
Always use bd update with flags:
# Update description bd update bd-a3f8 --description "New description" # Update with stdin for special characters echo 'Description with `backticks` and "quotes"' | bd update bd-a3f8 --description=- # Update multiple fields bd update bd-a3f8 --title "New title" --priority 0 --notes "Additional notes"
Agent-specific flags Always use these flags for programmatic use:
--json: Machine-readable output--quiet: Suppress progress messages--no-color: Disable color codes--claim: Atomically claim tasks
# Good agent commands bd ready --json --quiet bd create "Task" -p 1 --json bd update bd-a3f8 --claim --json --quiet # Bad agent commands (missing flags) bd ready # Human-readable output, hard to parse bd create "Task" -p 1 # No JSON output bd update bd-a3f8 --status in_progress --assignee me # Not atomic
Multi-agent coordination When multiple agents work on the same project:
Use atomic claim Always claim with --claim to prevent conflicts:
# Agent 1 bd update bd-a3f8 --claim # Successfully claims # Agent 2 (simultaneously) bd update bd-a3f8 --claim # Fails: already assigned
Sync frequently Pull before checking ready work:
git pull --rebase bd ready --json
Push after completing work:
bd close bd-a3f8 --reason "Done" git push
Use dependencies to coordinate Block dependent work:
# Agent 1 working on bd-a3f8 (auth) bd create "Add auth middleware" -p 1 --deps blocks:bd-a3f8 # Agent 2 sees bd-a3f8 is not ready (blocked) bd ready --json # bd-a3f8 not in list
Error handling Agents should handle common errors:
Issue already claimed bd update bd-a3f8 --claim # Error: Issue already assigned to agent-1 # Find other ready work bd ready --json
Merge conflicts git push # Error: merge conflict git pull --rebase # Resolve conflicts (Dolt handles cell-level merge) git push
Database locked bd create "Task" -p 1 # Error: database locked # Retry with exponential backoff sleep 1 && bd create "Task" -p 1
Integration with Claude, Copilot, Aider See the Integrations section for tool-specific setup:
Claude CLI + hooks approach with automatic context injection
Copilot MCP server for GitHub Copilot and VS Code
Aider Human-in-the-loop workflow with /run commands
Best practices
✅ Always use --json for programmatic output
✅ Use --claim for atomic task assignment
✅ Link discovered work with discovered-from
✅ Check bd ready before asking for work
✅ Push frequently to avoid conflicts
✅ Use bd prime for session context
Don’t
❌ Don’t use bd edit (interactive)
❌ Don’t parse human-readable output
❌ Don’t forget to push at session end
❌ Don’t create duplicate tracking (markdown TODOs)
❌ Don’t skip --claim when starting work
See also