Beads Issue Tracking Integration
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Beads Issue Tracking Integration is a specialized task-management system used within the Everything Claude Code (ECC) project to manage software development workflows. It utilizes the bd (beads) CLI tool to handle issues, tasks, and persistent project knowledge directly within the developer's environment, replacing traditional markdown-based TODO lists or external task managers.
The system integrates issue tracking with the underlying Git repository by storing issues in a local Dolt database. This architecture allows for seamless synchronization using Git remotes while maintaining a passive export of issues in .beads/issues.jsonl for visibility.
Sources: AGENTS.md:214-230, CLAUDE.md:76-88
System Architecture
Data Storage and Synchronization
The Beads integration relies on a dual-storage approach. Active issue data is managed within a Dolt database, providing robust versioning and querying capabilities. For synchronization across distributed teams, Beads utilizes a specific Git reference (refs/dolt/data) on the remote repository.
The diagram above illustrates the relationship between the local Dolt database, the passive JSONL export, and the remote Git synchronization.
Sources: AGENTS.md:231-233, CLAUDE.md:88
Components and Commands
The primary interface for the system is the bd CLI. Key commands allow developers to find work, claim tasks, and update progress without leaving the terminal.
| Command | Action | Purpose |
|---|---|---|
bd prime | Refresh Context | Shows full workflow context and detailed command reference. |
bd ready | Find Work | Lists available tasks and issues that are ready for implementation. |
bd show <id> | View Details | Displays the full content and metadata of a specific issue. |
bd update <id> --claim | Claim Work | Assigns an issue to the current agent/developer. |
bd remember | Persist Knowledge | Stores durable project memory; replaces MEMORY.md. |
bd close <id> | Complete Work | Marks an issue as finished and updates status in the DB. |
Sources: AGENTS.md:219-225, CLAUDE.md:82-86, AGENTS.md:254-260
Workflow Integration
Agent Context Profiles
The integration behaves differently based on the active "Agent Context Profile." These profiles define the level of autonomy an AI agent has regarding Git operations and Beads synchronization.
- Conservative (Default): Agents use
bdfor tracking but do not perform git commits or Dolt pushes without explicit approval. - Minimal: Standard conservative policy with tool instructions pointing to
bd prime. - Team-maintainer: Agents can close beads, run quality gates, and perform pushes during session completion if the repository opts in.
Sources: AGENTS.md:237-243, CLAUDE.md:91-97
Session Completion Protocol
When a development session ends, the Beads integration dictates a specific completion sequence to ensure repository integrity and task alignment.
The sequence diagram shows the steps taken during session completion, highlighting the conditional logic for Git synchronization.
Sources: AGENTS.md:245-260, CLAUDE.md:99-114
Integration Rules and Constraints
To maintain consistency, the project enforces strict rules regarding task management:
- Exclusive Use:
bdMUST be used for all task tracking. Developers are prohibited from usingTodoWrite,TaskCreate, or manual Markdown TODO lists. - Context Maintenance: The command
bd primemust be run whenever Beads context is stale. - Knowledge Persistence: Permanent project memory must reside in Beads (
bd remember) rather than temporaryMEMORY.mdfiles. - Authority: Explicit user or orchestrator instructions always override the Beads integration's default automation protocols.
Sources: AGENTS.md:227-230, CLAUDE.md:82-86, AGENTS.md:265-272
Summary
The Beads Issue Tracking Integration provides a Git-native, database-backed solution for managing development tasks in Everything Claude Code. By centralizing issues in Dolt and providing the bd CLI for agent interaction, it ensures that task status, project memory, and codebase changes remain synchronized and auditable throughout the software development lifecycle.