beads/docs/AIDER_INTEGRATION.md

Aider Integration Guide

This guide explains how to integrate Aider with Beads for AI-assisted coding with issue tracking.

Overview

Aider is an AI pair programming tool that works in your terminal. Unlike autonomous AI agents like Claude Code, Aider requires explicit user confirmation to run commands via the /run command.

The beads integration for Aider:

• Creates .aider.conf.yml with bd workflow instructions
• Provides .aider/README.md with quick reference
• Instructs the AI to suggest bd commands (not run them automatically)
• Works with aider's human-in-the-loop design philosophy

Installation

1. Install Beads

# Install beads CLI
go install github.com/steveyegge/beads/cmd/bd@latest

# Initialize in your project
cd your-project
bd init --quiet

2. Setup Aider Integration

# Install aider integration files
bd setup aider

# Verify installation
bd setup aider --check

This creates:

• .aider.conf.yml - Instructions for the AI about bd workflow
• .aider/README.md - Quick reference guide

3. Install Aider

# Install aider via pip
pip install aider-chat

# Or via pipx (recommended)
pipx install aider-chat

Usage Workflow

Starting a Session

1. Start aider in your project:

   cd your-project
   aider
   

2. Ask the AI about available work:

   You: What issues are ready to work on?
   
   Aider: Let me check the available work. Run:
   /run bd ready
   

3. Run the suggested command:

   /run bd ready
   

4. Choose an issue and ask AI to claim it:

   You: Let's work on bd-42
   
   Aider: Great choice! To claim it, run:
   /run bd update bd-42 --status in_progress
   

During Development

The AI will suggest appropriate bd commands as you work:

• Create issues for bugs you find:

  You: I found a bug in the auth code
  
  Aider: Let's track that. Run:
  /run bd create "Fix auth bug in login handler" --description="Login fails with 500 when password contains quotes" -t bug -p 1
  

• Link discovered work:

  Aider: Since we found this while working on bd-42, run:
  /run bd create "Fix auth bug" --description="..." -p 1 --deps discovered-from:bd-42
  

• Check issue details:

  /run bd show bd-42
  

Completing Work

When you're done:

You: This issue is complete

Aider: Great! Mark it complete by running:
/run bd close bd-42 --reason "Implemented login fix and added tests"

Then sync to git:
/run bd sync

Configuration

.aider.conf.yml

The config file contains instructions for the AI:

# Core workflow rules:
# 1. Track ALL work in bd (never use markdown TODOs)
# 2. Suggest 'bd ready' to find available work
# 3. Suggest 'bd create' for new issues/tasks/bugs
# 4. Suggest 'bd sync' at end of session
# 5. ALWAYS suggest commands - user will run them via /run

You can customize this file to add project-specific instructions.

Aider Commands vs bd Commands

Aider commands start with / and control aider itself:

• /run <command> - Run a shell command
• /add <file> - Add file to context
• /help - Show aider help

bd commands are run via /run:

• /run bd ready - Check available work
• /run bd create "..." - Create an issue
• /run bd show bd-42 - View issue details

Common Patterns

Starting Work

# Check what's available
/run bd ready

# Claim an issue
/run bd update bd-abc --status in_progress

Discovering Work

# Create a new issue
/run bd create "Refactor auth module" --description="Current auth code has tight coupling" -t task -p 2

# Link it to current work
/run bd dep add bd-new --type discovered-from --target bd-abc

Completing Work

# Close the issue
/run bd close bd-abc --reason "Implemented and tested"

# Sync to git
/run bd sync

Checking Status

# View issue details
/run bd show bd-abc

# List all open issues
/run bd list --status=open

# Check dependencies
/run bd dep tree bd-abc

Comparison: Aider vs Claude Code

Aider (Human-in-the-Loop)

• ✅ User must confirm all commands via /run
• ✅ Full control over what gets executed
• ✅ AI suggests bd commands
• ⚠️ More manual interaction required

Claude Code (Autonomous)

• ✅ AI directly executes bd commands
• ✅ Faster workflow (no confirmation needed)
• ✅ Hooks auto-inject bd context
• ⚠️ Less user control over command execution

Both approaches work well with beads! Choose based on your preference for automation vs. control.

Tips for Aider Users

1. Ask for Suggestions

Instead of running commands yourself, ask the AI:

You: How do I check what work is available?
Aider: Run `/run bd ready` to see all unblocked issues

2. Let the AI Track Work

The AI knows the bd workflow and will suggest appropriate commands:

You: I'm starting work on the login feature
Aider: First, let's claim it. Run:
/run bd update bd-xyz --status in_progress

3. Use bd prime for Context

Get the full workflow guide:

/run bd prime

The AI will read this and have complete context about bd commands.

4. Create Aliases

Add to your shell config for faster commands:

alias bdr='/run bd ready'
alias bdc='/run bd create'
alias bds='/run bd sync'

Then in aider:

bdr                    # Instead of /run bd ready
bdc "Fix bug" -t bug  # Instead of /run bd create "Fix bug" -t bug

Troubleshooting

"The AI isn't suggesting bd commands"

1. Check that .aider.conf.yml exists:

   bd setup aider --check
   

2. Reload aider to pick up the config:

   # Exit aider (Ctrl-D or /exit)
   # Restart aider
   aider
   

3. Explicitly ask about bd:

   You: What should I use for issue tracking?
   Aider: This project uses Beads (bd) for issue tracking...
   

"Commands are failing"

Make sure you're in a beads-initialized directory:

/run bd doctor

If not initialized:

/run bd init --quiet

"I want to remove the integration"

bd setup aider --remove

This removes .aider.conf.yml and .aider/README.md.

Advanced Usage

Multi-File Context

Aider can track multiple files. Combine with bd:

You: Add the auth files to context and check for related issues

/run bd list --json | grep -i auth
/add src/auth/*.py

Batch Operations

Run multiple bd commands in sequence:

# In your shell (not aider)
bd ready && bd show bd-42 && bd update bd-42 --status in_progress

Integration with Git

Aider handles git commits. bd tracks issues. They work together:

1. Claim issue: /run bd update bd-42 --status in_progress
2. Make changes with aider
3. Aider commits changes
4. Complete issue: /run bd close bd-42
5. Sync issues: /run bd sync

Example Session

$ aider

You: What issues are ready to work on?

Aider: Let me check. Run:
/run bd ready

📋 Ready work (3 issues with no blockers):
1. [P1] bd-42: Fix login bug
2. [P2] bd-99: Add password reset
3. [P3] bd-17: Refactor auth tests

You: Let's work on bd-42

Aider: Great! First claim it:
/run bd update bd-42 --status in_progress

You: Can you show me the details?

Aider: Run:
/run bd show bd-42

[Shows issue details]

You: Ok, add the auth files to context

Aider: Added src/auth/login.py and src/auth/utils.py

You: Fix the bug described in the issue

[Aider makes the changes]

You: Looks good! Mark it complete

Aider: Run:
/run bd close bd-42 --reason "Fixed login bug - added input validation"

Then sync:
/run bd sync

References

• Aider Documentation
• Beads Documentation
• AGENTS.md - Complete bd workflow guide
• QUICKSTART.md - Quick start guide