beads
Issue Tracker for agents
What is it?
Dependency-aware issue tracker for AI coding agents. Issues chain together like beads through four dependency types (blocks, related, parent-child, discovered-from). Local SQLite database syncs via git through JSONL export/import, acting like a distributed database without any server infrastructure.
WARNING: Alpha Status - Core features work but expect API changes before 1.0.
Features
- Dependency tracking - Chain issues together, detect cycles, visualize trees
- Ready work detection - Find unblocked issues automatically
- Git-synced - JSONL stored in git, auto-sync between database and files
- Hash-based IDs - Collision-resistant for multi-agent/multi-branch workflows
- Agent-optimized - JSON output, MCP server, CLI designed for programmatic use
- Multi-project - Auto-discovers databases by directory, complete isolation
- Extensible - Add your own SQLite tables alongside core schema
Installation
Quick install:
curl -fsSL https://raw.githubusercontent.com/shaneholloman/beads/main/scripts/install.sh | bash
Homebrew:
brew tap shaneholloman/beads
brew install beads
From source:
git clone https://github.com/shaneholloman/beads.git
cd beads
go build -o beads ./cmd/beads
sudo cp beads /usr/local/bin/beads # Or: cp beads ~/bin/beads
Other platforms: See installing.md for Windows, Arch Linux, IDE integration.
Quick Start
Initialize in your project:
cd your-project
beads init
Tell your AI agent:
echo "Use 'beads' for issue tracking. Run 'beads onboard' for instructions." AGENTS.md
Your agent handles the rest - creating issues, tracking dependencies, finding ready work.
Manual usage:
beads ready # Show unblocked work
beads create "Fix bug" -p 1 -t bug # Create issue
beads show beads-a1b2 # View details
beads dep tree beads-a1b2 # Visualize dependencies
beads close beads-a1b2 --reason "Done" # Mark complete
Core Concepts
Dependencies:
blocks - Hard blocker (affects ready work)related - Soft connectionparent-child - Epic/subtask hierarchydiscovered-from - Work found during execution
Priorities: 0 (critical) to 4 (backlog)
Types: bug, feature, task, epic, chore
Hash IDs: Collision-resistant identifiers (beads-a1b2, beads-f14c) instead of sequential numbers. See hash-id-design.md for details.
Git Workflow
beads auto-syncs with git:
beads create "Fix bug" -p 1
# After 5 seconds: exports to .beads/issues.jsonl
git add .beads/issues.jsonl
git commit -m "Working on fix"
git push
# On other machine:
git pull
beads ready # Auto-imports updated JSONL
Install git hooks for instant sync:
cd examples/git-hooks && ./install.sh
See advanced.md for merge conflict handling and daemon configuration.
Development
Build and test:
# Build local binary
go build -o beads ./cmd/beads
# Test locally
./beads version
./beads ready
# Run tests
go test ./...
# Install system-wide
cp ./beads ~/bin/beads
# or
sudo cp ./beads /usr/local/bin/beads
Version management:
./scripts/bump-version.sh 0.24.0 --commit # Bump all version files
git push origin main
Before committing:
go test ./... # All tests pass
go fmt ./... # Format code
golangci-lint run ./... # Check linting (see docs/linting.md for baseline)
See scripts/README.md for release process.
Documentation
License
MIT
shaneholloman