beads-task-tracking

Environment

Beads runs in its own DDEV container (ddev-{project}-beads). A wrapper script at /usr/local/bin/bd is installed in your container, so all bd commands work directly -- they are transparently delegated to the Beads container via SSH.

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

Session Start (ALWAYS DO THIS FIRST)

# 1. Check Beads is initialized. The beads container auto-initializes the
#    database on start — NEVER run `bd init` yourself (it can touch the
#    project's git state). If missing, ask the user to run `ddev restart`.
ls .beads/ 2>/dev/null || echo "Beads not initialized — ask the user to run: ddev restart"

# 2. Get context from previous sessions (prints a project/task summary — if it
#    prints without error, Beads is working)
bd prime

# 3. See what tasks are ready
bd ready --json

If bd fails

Symptom	Cause	Fix
bd: command not found or SSH errors	Beads container down	Ask the user to run ddev restart on the host
Unknown subcommand / flag error	Wrong syntax	Check available commands with bd --help
Command hangs	You ran bd edit	Never use bd edit — use bd update <id> --flags

Creating Tasks

bd create is NOT idempotent — running it twice creates two tasks. Before creating, check the task does not already exist (bd ready --json or bd list --json). If a previous create attempt failed ambiguously (e.g., SSH error), verify with bd ready --json before retrying.

# Create a task with priority (P0-P3)
bd create "Implement user authentication" -p 1 --json

# Create a subtask under a parent
bd create "Add validation for edge case" -p 2 --parent <parent-id> --json

# Create multiple tasks for a feature
bd create "Create service class" -p 1 --json
bd create "Add form handler" -p 1 --json
bd create "Write unit tests" -p 2 --json

Priority Levels