Skip to main content
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 init if there’s no .beads/ directory yet
  • aider installed: pip install aider-chat (or pipx 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

  1. Keep issues visible - Use bd prime to inject issue context
  2. Push regularly - Run bd dolt push after significant changes
  3. Use discovered-from - Track issues found during work
  4. Document context - Include descriptions in issues
  5. 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