Aider Integration

Integrate Beads with Aider for AI-assisted coding with human-in-the-loop issue tracking

Beads integrates with Aider to provide AI-assisted coding with structured issue tracking. Unlike autonomous agents, Aider follows a human-in-the-loop design where the AI suggests commands and you confirm them.

Overview

Aider is an AI pair programming tool that works in your terminal. The beads integration:

• 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)
• Respects aider’s human-in-the-loop philosophy

Aider requires explicit user confirmation to run commands via the /run command. This gives you full control over what gets executed.

Installation

1. Install Beads

   Install the Beads CLI:

   # Using Go
   go install github.com/steveyegge/beads/cmd/bd@latest
   
   # Or using Homebrew
   brew install beads
   
   # Or using npm
   npm install -g @beads/bd
   

   Initialize in your project:

   cd your-project
   bd init --quiet
   
2. Setup Aider integration

   Install aider integration files:

   bd setup aider
   

   This creates:

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

   Verify installation:

   bd setup aider --check
   
3. Install Aider

   Install aider via pip:

   # Using pipx (recommended)
   pipx install aider-chat
   
   # Or using pip
   pip install aider-chat
   

Usage Workflow

Starting a Session

1. Start aider

   cd your-project
   aider
   
2. Ask 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
   

   Aider displays ready issues with no blockers.

4. Claim an issue

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

During Development

The AI suggests appropriate bd commands as you work:

Creating Issues

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

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 --claim

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 execution
• AI suggests bd commands
• More manual interaction

Claude Code

Autonomous

• AI directly executes bd commands
• Faster workflow
• Hooks auto-inject bd context
• Less user control

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 --claim

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 --claim

Integration with Git

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

1. Claim issue: /run bd update bd-42 --claim
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 --claim

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

See Also

Aider Documentation

Official Aider documentation

Beads Quick Start

Learn Beads basics

Claude Code

Autonomous AI agent integration

Copilot Integration

Use Beads with GitHub Copilot