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

Getting Started

Core Concepts

Architecture

Workflows

Recovery

Multi-Agent

Integrations

Community

Reference

Setup

Prerequisites

Quick Setup

Verify Setup

Remove the Integration

Configuration

Workflow

Start Session

Inside Aider

During Work

End Session

Best Practices

Example Workflow

Troubleshooting

Config not loading

Issues not visible

See Also

​Setup

​Prerequisites

​Quick Setup

​Verify Setup

​Remove the Integration

​Configuration

​Workflow

​Start Session

​Inside Aider

​During Work

​End Session

​Best Practices

​Example Workflow

​Troubleshooting

​Config not loading

​Issues not visible

​See Also

Setup

Prerequisites

Quick Setup

Verify Setup

Remove the Integration

Configuration

Workflow

Start Session

Inside Aider

During Work

End Session

Best Practices

Example Workflow

Troubleshooting

Config not loading

Issues not visible

See Also