ddev-beads

A DDEV add-on that provides Beads (bd), a git-backed task tracker for AI agents, in a dedicated container. Other AI containers (OpenCode, Claude Code, Ralph) delegate task tracking to this container via docker exec.

Quick Start

# Install the add-on
ddev add-on get trebormc/ddev-beads
ddev restart

# Use from host
ddev bd ready
ddev bd create "Implement feature X" -p 1
ddev bd close bd-abc --reason "Done"

Prerequisites

DDEV >= v1.23.5

Installation

ddev add-on get trebormc/ddev-beads

This add-on is automatically installed as a dependency when you install ddev-opencode, ddev-claude-code, or ddev-ralph.

Architecture

┌──────────────────────────────────────────────────────────┐
│                    DDEV Docker Network                    │
│                                                          │
│  ┌──────────────┐                                        │
│  │   Beads      │  <-- docker exec from other containers │
│  │  Container   │                                        │
│  │  - bd CLI    │  Shared volume: /var/www/html/.beads/  │
│  │  - node 22   │                                        │
│  └──────────────┘                                        │
│        ^    ^    ^                                        │
│        │    │    │  docker exec $BEADS_CONTAINER bd ...   │
│        │    │    │                                        │
│  ┌─────┘    │    └─────┐                                 │
│  │          │          │                                  │
│  OpenCode  Claude   Ralph                                │
│            Code                                          │
└──────────────────────────────────────────────────────────┘

All AI containers access Beads via docker exec $BEADS_CONTAINER bd <command>. A wrapper function is installed in each container so that bd commands work transparently.

The .beads/ directory lives in the project root (/var/www/html/.beads/), shared across all containers via the project volume.

Commands

`ddev bd`

Execute Beads commands:

ddev bd ready                              # List ready tasks
ddev bd create "Implement login" -p 1      # Create task (P1 priority)
ddev bd update bd-abc --status in_progress # Mark in progress
ddev bd update bd-abc --notes "Working..." # Add progress notes
ddev bd close bd-abc --reason "Done"       # Close task
ddev bd sync                               # Sync state
ddev bd prime                              # Get context

Priority Levels

Level	Meaning
P0	Critical – blockers, security
P1	High – important features
P2	Medium – normal tasks
P3	Low – nice-to-haves

Part of DDEV AI Workspace

This add-on is part of DDEV AI Workspace, a modular ecosystem of DDEV add-ons for AI-powered Drupal development.

Repository	Description	Relationship
ddev-ai-workspace	Meta add-on that installs the full AI development stack with one command.	Workspace
ddev-opencode	OpenCode AI CLI container for interactive development.	Auto-installs this add-on
ddev-claude-code	Claude Code CLI container for interactive development.	Auto-installs this add-on
ddev-ralph	Autonomous AI task orchestrator. Delegates work to OpenCode or Claude Code.	Auto-installs this add-on
ddev-agents-sync	Auto-syncs AI agent repositories into a shared Docker volume.	Sibling dependency
ddev-playwright-mcp	Headless Playwright browser for browser automation and visual testing.	Sibling dependency
drupal-ai-agents	13 agents, 4 rules, 14 skills for Drupal development. Includes Beads workflow rule.	Uses Beads for task tracking

Disclaimer

This project is not affiliated with Anthropic, OpenCode, Beads, Playwright, Microsoft, or DDEV. AI-generated code may contain errors – always review changes before deploying to production. See menetray.com for more information and DruScan for Drupal auditing tools.

License

Apache-2.0. See LICENSE.