beads/docs/integrations/aider.md
Chris Sells 5c2fe0d496 docs: loss-check merge legacy docs/ originals into the site pages
Sixteen same-ground pairs reconciled: the ported website page won and every
fact living only in the older docs/ original was merged in before deleting
it (INSTALLING, SETUP, ARCHITECTURE, CONFIG, GIT_INTEGRATION, ADVANCED,
TROUBLESHOOTING, FAQ, MOLECULES, ROUTING, MULTI_REPO_AGENTS, and the five
agent-integration guides). The two divergent FAQs are now one canonical
FAQ with the comparison-first framing leading and pre-1.0 version gating
removed.

The routing pair inverted: the ported page described a routing system that
does not exist (bd routes, bd hydrate, .beads/routes.jsonl); the page was
rebuilt from the accurate sources (ROUTING.md + MULTI_REPO_AGENTS.md)
against the real surface (routing.mode config, role detection,
repos.primary/additional hydration, --repo override).

Every claim was verified against the Go source or the generated CLI
reference. Phantom surfaces removed across the corpus: bd pin/hook/pour/
wisp/routes/hydrate/reserve/lock/merge/stats, bd hooks status, bd vc
conflicts/log, bd dolt set shared-server, fictional beads_* MCP tool names
(real names taken from beads-mcp server.py), import.orphan_handling and
export.error_policy config keys, database.wal_mode/cache_size, stale
.beads/dolt/sql-server.log paths, and SQLite-era file paths. Notable
corrections: min_hash_length default is 3, .beads/metadata.json is
git-tracked, tombstone status is removed, wisps live in the main database
under an ephemeral flag.

Freshness markers moved with their content (configuration, ide-setup) and
the freshness gate + DOC_INVENTORY ledger now point at the new locations.
Load-bearing anchors preserved: #branchless-workflows-jujutsu--jj,
#circuit-breaker-server-appears-down-failing-fast, #extensible-database,
#multi-repo-hydration. Pointer stubs remain at docs/{SETUP,INSTALLING,
GIT_INTEGRATION}.md because released binaries print those paths
(allowlisted in the docsync guard).

Gates: go test ./test/docsync PASS; generate-cli-docs.sh --check PASS;
check-doc-freshness.sh PASS; mint broken-links: no broken links; mint dev
serves all sections (11 routes spot-checked at 200).
2026-07-12 10:37:07 -07:00

4.1 KiB

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

  1. Keep issues visible - Use bd prime to inject issue context
  2. Push regularly - Run bd dolt push after significant changes
  3. Use discovered-from - Track issues found during work
  4. Document context - Include descriptions in issues
  5. 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

See Also