- FAQ: fix bulk migration/export commands (tracker pull/push need explicit IDs; bulk lives on sync --pull-only / --pull / --push-only / --push) and correct the cross-project isolation claim (hydration + external targets) - quickstart: replace the broken DOLT.md blob URL with site links - installation: Quick Install Script heading matches its macOS/Linux/FreeBSD body - rewrite 33 stale SCREAMING_CASE link labels to the target pages' titles - add description frontmatter to the 55 authored pages missing it - docs.json: wildcard redirects for the old /next/ and version-prefixed route spaces (1.0.0, 1.0.4, 1.0.5)
4.3 KiB
| title | description |
|---|---|
| Aider | Set up beads with Aider's human-in-the-loop workflow, where the AI suggests bd commands you approve with /run |
How to use beads with Aider.
Aider is a human-in-the-loop AI pair programming tool: unlike autonomous agents such as Claude Code, it doesn't run shell commands on its own. The beads integration works with that design — the AI suggests bd commands, and you confirm each one with aider's /run command.
Setup
Prerequisites
- beads installed and initialized in your project (see Installation); run
bd initif there's no.beads/directory yet - aider installed:
pip install aider-chat(orpipx install aider-chat)
Quick Setup
bd setup aider
This creates:
.aider.conf.yml— tells aider to load the beads instructions.aider/BEADS.md— workflow instructions the AI reads.aider/README.md— quick reference for humans
Verify Setup
bd setup aider --check
Remove the Integration
bd setup aider --remove
This removes .aider.conf.yml, .aider/BEADS.md, and .aider/README.md.
Configuration
The generated .aider.conf.yml loads the beads instructions into aider's read-only context:
# Beads Issue Tracking Integration for Aider
# Auto-generated by 'bd setup aider'
# Load Beads workflow instructions for the AI
# This file is marked read-only and cached for efficiency
read:
- .aider/BEADS.md
.aider/BEADS.md holds the workflow rules the AI follows: track all work in bd (never markdown TODOs), suggest bd ready to find work, suggest bd create for new issues, suggest bd dolt push at end of session — and always suggest commands for you to run via /run. You can edit it to add project-specific instructions, but rerunning bd setup aider regenerates it.
Workflow
Start Session
# Aider will have access to issues via .aider.conf.yml
aider
# Or manually inject context
bd prime | aider --message-file -
Inside Aider
Aider's own commands start with / (/run, /add, /help); anything else is a message to the AI. The AI suggests bd commands, and you execute the ones you approve with /run:
You: What issues are ready to work on?
Aider: Let me check the available work. Run:
/run bd ready
You: Let's work on bd-42
Aider: To claim it, run:
/run bd update bd-42 --claim
To give the AI full bd context mid-session, run /run bd prime — the AI reads the output and picks up the complete workflow guide.
During Work
Use bd commands alongside aider:
# In another terminal or after exiting aider
bd create "Found bug during work" --deps discovered-from:bd-42 --json
bd update bd-42 --claim
bd ready
# Link an already-created issue as discovered work
bd dep add bd-77 bd-42 --type discovered-from
End Session
bd dolt push
Best Practices
- Keep issues visible - Use
bd primeto inject issue context - Push regularly - Run
bd dolt pushafter significant changes - Use discovered-from - Track issues found during work
- Document context - Include descriptions in issues
- Aider commits, bd syncs - Aider auto-commits your code changes; issue data moves separately with
bd dolt push
Example Workflow
# 1. Check ready work
bd ready
# 2. Start aider with issue context
aider --message "Working on bd-42: Fix auth bug"
# 3. Work in aider...
# 4. Create discovered issues
bd create "Found related bug" --deps discovered-from:bd-42 --json
# 5. Complete and push
bd close bd-42 --reason "Fixed"
bd dolt push
Troubleshooting
Config not loading
# Check config exists
cat .aider.conf.yml
# Regenerate
bd setup aider
Aider reads .aider.conf.yml at startup, so restart aider (/exit, then aider) after regenerating.
Issues not visible
# Use bd prime to inject issue context
bd prime | aider --message-file -
# Or check database health
bd doctor
See Also
- Claude Code
- IDE Setup
- Quickstart
- Aider documentation
- AGENTS.md - the full bd agent workflow guide