Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/steveyegge/beads/llms.txt

Use this file to discover all available pages before exploring further.

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

  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...
Make sure you’re in a beads-initialized directory:
/run bd doctor
If not initialized:
/run bd init --quiet

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

Build docs developers (and LLMs) love

Get started for freeTalk to us