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

Part of DDEV AI Workspace — a modular ecosystem of DDEV add-ons for AI-powered Drupal development. Install the full stack with one command: ddev add-on get trebormc/ddev-ai-workspace

Created by Robert Menetray · Sponsored by DruScan

Why a separate container? Task tracking runs in its own container so that all AI tools (OpenCode, Claude Code, Ralph) share the same task state without conflicts. Each container accesses Beads via a lightweight bd wrapper that delegates to ssh beads bd, keeping the task data centralized in the project’s .beads/ directory.

Quick Start

The recommended way to install this add-on is through the DDEV AI Workspace, which installs all tools and dependencies with a single command:

ddev add-on get trebormc/ddev-ai-workspace
ddev restart

This add-on is also automatically installed as a dependency when you install ddev-opencode, ddev-claude-code, or ddev-ralph. You rarely need to install it directly.

Standalone installation

If you need to install it individually (requires familiarity with the DDEV add-on ecosystem):

ddev add-on get trebormc/ddev-beads
ddev restart

Usage

ddev bd ready
ddev bd create "Implement feature X" -p 1
ddev bd close bd-abc --reason "Done"

Prerequisites

• DDEV >= v1.24.10

Architecture

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

All AI containers access Beads via ssh beads 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 prime                              # Get context

Priority Levels

Uninstallation

ddev add-on remove ddev-beads
ddev restart

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.

Disclaimer

This project is an independent initiative by Robert Menetray, sponsored by DruScan. It is not affiliated with Anthropic, OpenCode, Beads, Playwright, Microsoft, or DDEV. AI-generated code may contain errors. Always review changes before deploying to production.

License

Apache-2.0. See LICENSE.