> ## 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.

# Aider Integration

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

Beads integrates with [Aider](https://aider.chat/) 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

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

## Installation

<Steps>
  <Step title="Install Beads">
    Install the Beads CLI:

    ```bash theme={null}
    # 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:

    ```bash theme={null}
    cd your-project
    bd init --quiet
    ```
  </Step>

  <Step title="Setup Aider integration">
    Install aider integration files:

    ```bash theme={null}
    bd setup aider
    ```

    This creates:

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

    Verify installation:

    ```bash theme={null}
    bd setup aider --check
    ```
  </Step>

  <Step title="Install Aider">
    Install aider via pip:

    ```bash theme={null}
    # Using pipx (recommended)
    pipx install aider-chat

    # Or using pip
    pip install aider-chat
    ```
  </Step>
</Steps>

## Usage Workflow

### Starting a Session

<Steps>
  <Step title="Start aider">
    ```bash theme={null}
    cd your-project
    aider
    ```
  </Step>

  <Step title="Ask about available work">
    ```
    You: What issues are ready to work on?

    Aider: Let me check the available work. Run:
    /run bd ready
    ```
  </Step>

  <Step title="Run the suggested command">
    ```
    /run bd ready
    ```

    Aider displays ready issues with no blockers.
  </Step>

  <Step title="Claim an issue">
    ```
    You: Let's work on bd-42

    Aider: Great choice! To claim it, run:
    /run bd update bd-42 --claim
    ```
  </Step>
</Steps>

### During Development

The AI suggests appropriate bd commands as you work:

<CodeGroup>
  ```bash Creating Issues theme={null}
  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
  ```

  ```bash Linking Discovered Work theme={null}
  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
  ```

  ```bash Checking Details theme={null}
  /run bd show bd-42
  ```
</CodeGroup>

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

```yaml theme={null}
# 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

```bash theme={null}
# Check what's available
/run bd ready

# Claim an issue
/run bd update bd-abc --claim
```

### Discovering Work

```bash theme={null}
# 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

```bash theme={null}
# Close the issue
/run bd close bd-abc --reason "Implemented and tested"

# Sync to git
/run bd sync
```

### Checking Status

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="Aider" icon="user">
    **Human-in-the-Loop**

    * User must confirm all commands via `/run`
    * Full control over execution
    * AI suggests bd commands
    * More manual interaction
  </Card>

  <Card title="Claude Code" icon="bolt">
    **Autonomous**

    * AI directly executes bd commands
    * Faster workflow
    * Hooks auto-inject bd context
    * Less user control
  </Card>
</CardGroup>

<Tip>
  **Both approaches work well with beads!** Choose based on your preference for automation vs. control.
</Tip>

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

```bash theme={null}
/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:

```bash theme={null}
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

<AccordionGroup>
  <Accordion title="The AI isn't suggesting bd commands">
    1. Check that `.aider.conf.yml` exists:
       ```bash theme={null}
       bd setup aider --check
       ```

    2. Reload aider to pick up the config:
       ```bash theme={null}
       # 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...
       ```
  </Accordion>

  <Accordion title="Commands are failing">
    Make sure you're in a beads-initialized directory:

    ```bash theme={null}
    /run bd doctor
    ```

    If not initialized:

    ```bash theme={null}
    /run bd init --quiet
    ```
  </Accordion>

  <Accordion title="I want to remove the integration">
    ```bash theme={null}
    bd setup aider --remove
    ```

    This removes `.aider.conf.yml` and `.aider/README.md`.
  </Accordion>
</AccordionGroup>

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

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="Aider Documentation" icon="book" href="https://aider.chat/docs/">
    Official Aider documentation
  </Card>

  <Card title="Beads Quick Start" icon="rocket" href="/quickstart">
    Learn Beads basics
  </Card>

  <Card title="Claude Code" icon="code" href="/integrations/claude">
    Autonomous AI agent integration
  </Card>

  <Card title="Copilot Integration" icon="github" href="/integrations/copilot">
    Use Beads with GitHub Copilot
  </Card>
</CardGroup>