Aider

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

Keep issues visible - Use bd prime to inject issue context
Push regularly - Run bd dolt push after 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