Beads: A Git-Friendly Issue Tracker for AI Coding Agents
AI coding agents have transformed software development workflows, offering the ability to write code, fix bugs, and accelerate project timelines. However, these agents face a fundamental constraint: finite memory, commonly known as the context window. As conversations grow and files accumulate, the context window fills up. When you start a new session, the agent loses all previous understanding of the project's goals, progress, and architecture. This creates a persistent challenge in maintaining continuity across development sessions.
Beads addresses this problem through a structured, Git-native issue tracking system designed specifically for AI agents. This guide explores how Beads provides persistent memory for AI agents, enabling them to manage complex tasks, understand dependencies, and maintain project context across multiple sessions.
The context window problem
AI agents operate within a defined context window, representing the maximum amount of text the model can consider simultaneously. This includes your prompts, conversation history, and any provided files.
Consider a typical development workflow: you explain requirements to your AI agent, which then generates code. Through iterative refinement and conversation, the context window gradually fills. Once full, you face two options: remove older conversation segments, potentially losing crucial information, or start a completely new chat session. Starting fresh means the agent has no memory of previous work. When asked "What were we working on?", the agent responds as if the project doesn't exist, because from its perspective, the conversation has just begun.
Limitations of simple task files
A common workaround involves maintaining a TASKS.md file that outlines the project plan. This file gets loaded at the start of each session to provide context. While better than nothing, this approach has significant drawbacks:
Context consumption: For large projects, the task file itself can be lengthy, consuming substantial portions of the context window before actual work begins.
Priority and dependency ambiguity: A flat markdown list doesn't explicitly define relationships between tasks. An agent might struggle to understand that Task C depends on completing Task A and Task B first. This leads to incorrect execution order or failure to grasp project hierarchy.
State management issues: The agent must read, parse, and modify the markdown file to update task completion status. This process is error-prone and inefficient, as the entire file requires reprocessing with every update.
Beads provides a more robust, structured, and context-efficient solution to these challenges.
Architecture and core concepts
Beads combines the speed of a local database with Git's collaborative power through an elegant three-part architecture.
SQLite database storage
At its core, Beads uses a local SQLite database (beads.db) stored within a .beads folder in your project directory. This database holds all issues, their statuses, priorities, descriptions, and relationships. SQLite's lightweight nature enables efficient querying, allowing agents to request specific information (such as "what is the next ready task?") without loading the entire project history into context.
Git-friendly JSON-L format
Storing binary SQLite files directly in Git creates problems. Binary files aren't human-readable, and any change results in a completely new binary file, making merges and conflict resolution nearly impossible. Beads solves this with a companion file: issues.jsonl. JSON-L (JSON Lines) is a text format where each line represents a valid JSON object. When changes occur in the SQLite database, a background daemon automatically exports changes as new lines in the issues.jsonl file. This text file is the only issue-related file committed to Git.
Two-way sync mechanism
This dual-system architecture enables seamless collaboration:
Pushing changes: When User A closes an issue, the local SQLite database updates. The Beads daemon appends a new JSON object representing this change to issues.jsonl. User A commits and pushes this text file to the remote repository.
Pulling changes: When User B pulls from the repository, they receive the updated issues.jsonl file. Their local Beads daemon detects the change and automatically imports the new information, updating their local SQLite database to match.
This architecture ensures all collaborators, whether human or AI, maintain a perfectly synchronized, up-to-date view of project status while leveraging Git's familiar workflow.
Installation and initialization
Beads is written in Go, requiring Go installation to build from source. Git is also necessary for version control.
The installation process involves cloning the repository and building the bd CLI tool:
git clone https://github.com/sourcegraph/beads.git
cd beads
go install ./cmd/bd
This compiles the source and places the bd executable in your Go bin directory, which should be in your system's PATH.
Project initialization
Initializing Beads in a project requires running a single command from the project's root directory:
bd init
This creates the .beads directory with all necessary files. You can then configure Beads for your environment and AI model:
bd onboard
Alternatively, for specific models like Claude:
bd setup claude
This guides you through API key setup and other configuration details.
Understanding the .beads directory
The .beads folder contains several important files:
beads.db: The primary SQLite database storing all project issues locally.
beads.db-shm and beads.db-wal: Temporary files used by SQLite's Write-Ahead Logging (WAL) mode for improved performance and concurrent read access.
issues.jsonl: The text-based log of all database changes. This is the file you commit to Git.
config.yaml: Local configuration file containing API keys and model preferences. Typically added to .gitignore to avoid committing secrets.
daemon.*: Files related to the background daemon process (daemon.log, daemon.pid, daemon.lock) handling automatic synchronization between beads.db and issues.jsonl.
bd.sock: A Unix socket file enabling communication between the bd CLI, AI agents, and the Beads database.
Creating and organizing issues
Beads uses a hierarchical issue structure built around epics, tasks, and dependencies. Consider building a React application for viewing Homebrew packages as an example project.
Defining the project epic
An epic represents a high-level project goal. Creating an epic involves specifying its title, type, priority, and description:
bd create "Brew UI" -t epic -p 1 --description="A React application to view, search, and manage Homebrew-installed packages with beautiful UI and dependency visualization"
This command creates an issue with:
- Title: "Brew UI"
- Type: epic (a large, multi-task feature)
- Priority: P1 (highest priority)
- Detailed description for AI understanding
Verifying the creation:
bd stats
Total Issues: 1
Open: 1
Closed: 0
AI-driven task breakdown
Rather than manually decomposing epics into subtasks, you can delegate this planning to an AI agent. The agent queries the database to find the epic, analyzes its description, formulates a plan, and creates linked subtasks automatically.
An agent given the prompt "Read the epic from beads and create issues under the epic that make sense to complete the task" will:
- Query the database for the epic
- Analyze its requirements
- Generate logical subtasks (setup, component creation, dependency visualization)
- Execute
bd createcommands linking new issues to the parent epic
Visualizing project structure
Viewing all issues in a flat list:
bd list
For a hierarchical view showing relationships:
bd dep tree brew-ui-eci --direction=both
The tree view displays project structure and task relationships clearly, providing shared understanding for both human developers and AI agents.
The development workflow
Beads enables a structured, dependency-aware workflow for AI agents.
Identifying ready tasks
The bd ready command queries the database for all open issues with no uncompleted dependencies. This ensures agents always work on tasks in the correct order:
bd ready
ID: setup-react-xyz
Title: Set up React project structure
Priority: P1
Status: open
ID: install-deps-abc
Title: Install required dependencies
Priority: P1
Status: open
The agent work loop
An AI agent's workflow becomes a predictable cycle:
- Check for ready work: Run
bd readyto get actionable tasks - Select a task: Pick the highest priority task from the list
- Update status: Mark the task as in progress
bd update <issue-id> --status in_progress
- Perform the work: Write code, create files, or complete required actions
- Mark as complete: Close the issue after verification
bd close <issue-id> --reason "Implemented"
- Repeat: Return to step 1, as completing one task may unblock others
This loop continues until bd ready returns no open issues, indicating project completion.
Advanced capabilities
Web interface
While the CLI provides power and precision, Beads includes a web UI for graphical overview. The interface presents a table-based view of all issues, allowing quick assessment of project status without terminal commands.
Jira integration
For teams using Jira as their primary project management tool, Beads provides scripts enabling two-way synchronization. You can import issues from Jira projects into your local Beads database and export Beads-created issues back to Jira. This bridges the gap between agent-friendly local workflows and company-wide project tracking systems.
Database compaction
Large projects accumulate thousands of issues over time. The bd compact command implements "agentic memory decay" to manage database growth:
- Analysis: Identify old, closed issues (such as those closed more than 30 days ago)
- Summarization: Use an LLM to read full issue content and generate concise summaries
- Application: Replace detailed issue content with generated summaries, marking them as "compacted"
This intelligently reduces database size by discarding fine-grained details of completed work while preserving essential context, similar to human memory consolidation.
Comparison with spec-driven development
Beads differs significantly from spec-driven development methodologies in its approach to managing project context.
Context efficiency
Spec-driven development relies on detailed markdown files describing the entire project. Agents often need to load complete spec files into their context window, which is inefficient and leaves less room for code and conversation.
Beads treats the project plan as a queryable database. Agents make small, targeted queries to retrieve only information needed for immediate tasks. This is substantially more context-efficient, especially for large projects. Developers can clear context freely, knowing agents can restore understanding through database queries.
Dependency management
Spec-driven development often describes dependencies implicitly through natural language. Agents must infer that one section depends on another, which can be unreliable and error-prone.
Beads makes dependencies explicit first-class citizens of the data model. Relationships are stored structurally in the database. When agents query the dependency graph, there's no ambiguity about execution order.
Hybrid approaches
A hybrid methodology combines strengths of both approaches:
- Plan with specs: Create detailed markdown files outlining project goals, user stories, and technical requirements
- Execute with Beads: Feed the initial plan to an AI agent, instructing it to convert the plan into structured epics, tasks, and dependencies within Beads
- Develop: Use Beads workflow for day-to-day development, leveraging its context efficiency and robust dependency management
This approach provides detailed upfront planning while maintaining execution efficiency and persistent memory throughout development.
Final thoughts
Beads transforms AI coding agent collaboration by replacing chat logs and markdown files with a version-controlled database, providing persistent memory for larger projects.
It reduces context loss, supports dependency tracking, and allows easy collaboration with Git sync. Its SQLite-JSONL design balances local speed and team collaboration.
With agents querying only needed info, Beads saves context space and makes AI assistants more reliable and long-term.
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.