Repository: gastownhall/beads

Stars: 20860

CLAUDE.md Copy Chapter

Instructions for AI Agents Working on Beads

Project Overview Copy Chapter

This is beads (command: bd), an issue tracker designed for AI-supervised coding workflows. We dogfood our own tool!

Issue Tracking Copy Chapter

We use bd (beads) for issue tracking instead of Markdown TODOs or external tools.

Quick Reference Copy Section

Find ready work (no blockers)

bd ready --json
Find ready work including future deferred issues

bd ready --include-deferred --json
Create new issue

bd create "Issue title" -t bug|feature|task -p 0-4 -d "Description" --json
Create issue with due date and defer (GH#820)

bd create "Task" --due=+6h              # Due in 6 hours
bd create "Task" --defer=tomorrow       # Hidden from bd ready until tomorrow
bd create "Task" --due="next monday" --defer=+1h  # Both
Update issue status

bd update <id> --status in_progress --json
Update issue with due/defer dates

bd update <id> --due=+2d                # Set due date
bd update <id> --defer=""               # Clear defer (show immediately)
Link discovered work

bd dep add <discovered-id> <parent-id> --type discovered-from
Complete work

bd close <id> --reason "Done" --json
Show dependency tree

bd dep tree <id>
Get issue details

bd show <id> --json
Query issues by time-based scheduling (GH#820)

bd list --deferred              # Show issues with defer_until set
bd list --defer-before=tomorrow # Deferred before tomorrow
bd list --defer-after=+1w       # Deferred after one week from now
bd list --due-before=+2d        # Due within 2 days
bd list --due-after="next monday" # Due after next Monday
bd list --overdue               # Due date in past (not closed)

Workflow Copy Section

1. Check for ready work: Run bd ready to see what's unblocked
2. Claim your task: bd update <id> --status in_progress
3. Work on it: Implement, test, document
4. Discover new work: If you find bugs or TODOs, create issues:
- bd create "Found bug in auth" -t bug -p 1 --json
- Link it: bd dep add <new-id> <current-id> --type discovered-from
5. Complete: bd close <id> --reason "Implemented"
6. Export: Run bd export -o .beads/issues.jsonl before committing

Issue Types Copy Section

- bug - Something broken that needs fixing
- feature - New functionality
- task - Work item (tests, docs, refactoring)
- epic - Large feature composed of multiple issues
- chore - Maintenance work (dependencies, tooling)

Priorities Copy Section

- 0 - Critical (security, data loss, broken builds)
- 1 - High (major features, important bugs)
- 2 - Medium (nice-to-have features, minor bugs)
- 3 - Low (polish, optimization)
- 4 - Backlog (future ideas)

Dependency Types Copy Section

- blocks - Hard dependency (issue X blocks issue Y)
- related - Soft relationship (issues are connected)
- parent-child - Epic/subtask relationship
- discovered-from - Track issues discovered during work

Only blocks dependencies affect the ready work queue.

Development Guidelines Copy Chapter

Code Standards Copy Section

- Go version: 1.21+
- Linting: golangci-lint run ./... (baseline warnings documented in LINTING.md)
- Testing: All new features need tests (go test ./...)
- Documentation: Update relevant .md files

File Organization Copy Section

beads/
├── cmd/bd/              # CLI commands
├── internal/
│   ├── types/           # Core data types
│   └── storage/         # Storage layer
│       └── sqlite/      # SQLite implementation
├── examples/            # Integration examples
└── *.md                 # Documentation

Before Committing Copy Section

1. Run tests: go test ./...
2. Run linter: golangci-lint run ./... (ignore baseline warnings)
3. Export issues: bd export -o .beads/issues.jsonl
4. Update docs: If you changed behavior, update README.md or other docs
5. Git add both: git add .beads/issues.jsonl <your-changes>

Git Workflow Copy Section

Make changes

git add <files>
Export beads issues

bd export -o .beads/issues.jsonl
git add .beads/issues.jsonl
Commit

git commit -m "Your message"
After pull

git pull
bd import .beads/issues.jsonl  # Sync Dolt database

Or use the git hooks in examples/git-hooks/ for automation.

Current Project Status Copy Chapter

Run bd stats to see overall progress.

Active Areas Copy Section

- Core CLI: Mature, but always room for polish
- Examples: Growing collection of agent integrations
- Documentation: Comprehensive but can always improve
- MCP Server: Planned (see bd-5)
- Migration Tools: Planned (see bd-6)

1.0 Milestone Copy Section

We're working toward 1.0. Key blockers tracked in bd. Run:

bd dep tree bd-8  # Show 1.0 epic dependencies

Common Tasks Copy Chapter

Adding a New Command Copy Section

1. Create file in cmd/bd/
2. Add to root command in cmd/bd/main.go
3. Implement with Cobra framework
4. Add --json flag for agent use
5. Add tests in cmd/bd/*_test.go
6. Document in README.md

Adding Storage Features Copy Section

1. Update schema in internal/storage/sqlite/schema.go
2. Add migration if needed
3. Update internal/types/types.go if new types
4. Implement in internal/storage/sqlite/sqlite.go
5. Add tests
6. Update export/import in cmd/bd/export.go and cmd/bd/import.go

Adding Examples Copy Section

1. Create directory in examples/
2. Add README.md explaining the example
3. Include working code
4. Link from examples/README.md
5. Mention in main README.md

Questions? Copy Chapter

- Check existing issues: bd list
- Look at recent commits: git log --oneline -20
- Read the docs: README.md, TEXT_FORMATS.md, EXTENDING.md
- Create an issue if unsure: bd create "Question: ..." -t task -p 2

Important Files Copy Chapter

- README.md - Main documentation (keep this updated!)
- EXTENDING.md - Database extension guide
- TEXT_FORMATS.md - JSONL format analysis
- CONTRIBUTING.md - Contribution guidelines
- SECURITY.md - Security policy

Pro Tips for Agents Copy Chapter

- Always use --json flags for programmatic use
- Link discoveries with discovered-from to maintain context
- Check bd ready before asking "what next?"
- Export to JSONL before committing (or use git hooks)
- Use bd dep tree to understand complex dependencies
- Priority 0-1 issues are usually more important than 2-4

Visual Design System Copy Chapter

When adding CLI output features, follow these design principles for consistent, cognitively-friendly visuals.

CRITICAL: No Emoji-Style Icons Copy Section

NEVER use large colored emoji icons like 🔴🟠🟡🔵⚪ for priorities or status.
These cause cognitive overload and break visual consistency.

ALWAYS use small Unicode symbols with semantic colors applied via lipgloss:
- Status: ○ ◐ ● ✓ ❄
- Priority: ● (filled circle with color)

Status Icons (use consistently across all commands) Copy Section

○ open        - Available to work (white/default)
◐ in_progress - Currently being worked (yellow)
● blocked     - Waiting on dependencies (red)
✓ closed      - Completed (muted gray)
❄ deferred    - Scheduled for later (blue/muted)

Priority Icons and Colors Copy Section

Format: ● P0 (filled circle icon + label, colored by priority)

- ● P0: Red + bold (critical)
- ● P1: Orange (high)
- ● P2-P4: Default text (normal)

Issue Type Colors Copy Section

- bug: Red (problems need attention)
- epic: Purple (larger scope)
- Others: Default text

Design Principles Copy Section

1. Small Unicode symbols only - NO emoji blobs (🔴🟠 etc.)
2. Semantic colors only for actionable items - Don't color everything
3. Closed items fade - Use muted gray to show "done"
4. Icons > text labels - More scannable, less cognitive load
5. Consistency across commands - Same icons in list, graph, show, etc.
6. Tree connectors - Use ├──, └──, │ for hierarchies (file explorer pattern)
7. Reduce cognitive noise - Don't show "needs:1" when it's just the parent epic

Semantic Styles (internal/ui/styles.go) Copy Section

Use exported styles from the ui package:

// Status styles
ui.StatusInProgressStyle  // Yellow - active work
ui.StatusBlockedStyle     // Red - needs attention
ui.StatusClosedStyle      // Muted gray - done
// Priority styles
ui.PriorityP0Style        // Red + bold
ui.PriorityP1Style        // Orange
// Type styles
ui.TypeBugStyle           // Red
ui.TypeEpicStyle          // Purple
// General styles
ui.PassStyle, ui.WarnStyle, ui.FailStyle
ui.MutedStyle, ui.AccentStyle
ui.RenderMuted(text), ui.RenderAccent(text)

Example Usage Copy Section

// Status icon with semantic color
switch issue.Status {
case types.StatusOpen:
    icon = "○"  // no color - available but not urgent
case types.StatusInProgress:
    icon = ui.StatusInProgressStyle.Render("◐")  // yellow
case types.StatusBlocked:
    icon = ui.StatusBlockedStyle.Render("●")     // red
case types.StatusClosed:
    icon = ui.StatusClosedStyle.Render("✓")      // muted
}

Building and Testing Copy Chapter

Build

go build -o bd ./cmd/bd
Test

go test ./...
Test with coverage

go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out
Run locally

./bd init --prefix test
./bd create "Test issue" -p 1
./bd ready

Release Process (Maintainers) Copy Chapter

1. Update version in code (if applicable)
2. Update CHANGELOG.md (if exists)
3. Run full test suite
4. Tag release: git tag v0.x.0
5. Push tag: git push origin v0.x.0
6. GitHub Actions handles the rest

---

Remember: We're building this tool to help AI agents like you! If you find the workflow confusing or have ideas for improvement, create an issue with your feedback.

Happy coding!

README.md Copy Chapter

bd - Beads

Distributed graph issue tracker for AI agents, powered by Dolt.

Platforms: macOS, Linux, Windows, FreeBSD


Docs: https://gastownhall.github.io/beads/

Beads provides a persistent, structured memory for coding agents. It replaces messy markdown plans with a dependency-aware graph, allowing agents to handle long-horizon tasks without losing context.

⚡ Quick Start Copy Chapter

Install beads CLI (system-wide - don't clone this repo into your project)

curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
Initialize in YOUR project

cd your-project
bd init
Tell your agent

echo "Use 'bd' for task tracking" >> AGENTS.md

Note: Beads is a CLI tool you install once and use everywhere. You don't need to clone this repository into your project.

🛠 Features Copy Chapter

* Dolt-Powered: Version-controlled SQL database with cell-level merge, native branching, and built-in sync via Dolt remotes.
* Agent-Optimized: JSON output, dependency tracking, and auto-ready task detection.
* Zero Conflict: Hash-based IDs (bd-a1b2) prevent merge collisions in multi-agent/multi-branch workflows.
* Compaction: Semantic "memory decay" summarizes old closed tasks to save context window.
* Messaging: Message issue type with threading (--thread), ephemeral lifecycle, and mail delegation.
* Graph Links: relates_to, duplicates, supersedes, and replies_to for knowledge graphs.

📖 Essential Commands Copy Chapter

| Command | Action |
| --- | --- |
| bd ready | List tasks with no open blockers. |
| bd create "Title" -p 0 | Create a P0 task. |
| bd update <id> --claim | Atomically claim a task (sets assignee + in_progress). |
| bd dep add <child> <parent> | Link tasks (blocks, related, parent-child). |
| bd show <id> | View task details and audit trail. |

🔗 Hierarchy & Workflow Copy Chapter

Beads supports hierarchical IDs for epics:

* bd-a3f8 (Epic)
* bd-a3f8.1 (Task)
* bd-a3f8.1.1 (Sub-task)

Stealth Mode: Run bd init --stealth to use Beads locally without committing files to the main repo. Perfect for personal use on shared projects. See Git-Free Usage below.

Contributor vs Maintainer: When working on open-source projects:

* Contributors (forked repos): Run bd init --contributor to route planning issues to a separate repo (e.g., ~/.beads-planning). Keeps experimental work out of PRs.
* Maintainers (write access): Beads auto-detects maintainer role via SSH URLs or HTTPS with credentials. Only need git config beads.role maintainer if using GitHub HTTPS without credentials but you have write access.

📦 Installation Copy Chapter

brew install beads           # macOS / Linux (recommended)
npm install -g @beads/bd     # Node.js users

Other methods: install script | go install | from source | Windows | Arch AUR

Requirements: macOS, Linux, Windows, or FreeBSD. See docs/INSTALLING.md for complete installation guide.

Security And Verification Copy Section

Before trusting any downloaded binary, verify its checksum against the release checksums.txt.

The install scripts verify release checksums before install. For manual installs, do this verification yourself before first run.

On macOS, scripts/install.sh preserves the downloaded signature by default. Local ad-hoc re-signing is explicit opt-in via BEADS_INSTALL_RESIGN_MACOS=1.

See docs/ANTIVIRUS.md for Windows AV false-positive guidance and verification workflow.

💾 Storage Modes Copy Chapter

Beads uses Dolt as its database. Two modes
are available:

Embedded Mode (default) Copy Section

bd init

Dolt runs in-process — no external server needed. Data lives in
.beads/embeddeddolt/. Single-writer only (file locking enforced).
This is the recommended mode for most users.

Server Mode Copy Section

bd init --server

Connects to an external dolt sql-server. Data lives in .beads/dolt/.
Supports multiple concurrent writers. Configure the connection with flags
or environment variables:

| Flag | Env Var | Default |
|------|---------|---------|
| --server-host | BEADS_DOLT_SERVER_HOST | 127.0.0.1 |
| --server-port | BEADS_DOLT_SERVER_PORT | 3307 |
| --server-user | BEADS_DOLT_SERVER_USER | root |
| | BEADS_DOLT_PASSWORD | (none) |

Backup & Migration Copy Section

Back up your database and migrate between modes using bd backup:

Set up a backup destination and push

bd backup init /path/to/backup
bd backup sync
Restore into a new project (any mode)

bd init           # or bd init --server
bd backup restore --force /path/to/backup

See docs/DOLT.md for full
migration instructions.

🌐 Community Tools Copy Chapter

See docs/COMMUNITY_TOOLS.md for a curated list of community-built UIs, extensions, and integrations—including terminal interfaces, web UIs, editor extensions, and native apps.

🚀 Git-Free Usage Copy Chapter

Beads works without git. The Dolt database is the storage backend — git
integration (hooks, repo discovery, identity) is optional.

Initialize without git

export BEADS_DIR=/path/to/your/project/.beads
bd init --quiet --stealth
All core commands work with zero git calls

bd create "Fix auth bug" -p 1 -t bug
bd ready --json
bd update bd-a1b2 --claim
bd prime
bd close bd-a1b2 "Fixed"

BEADS_DIR tells bd where to put the .beads/ database directory,
bypassing git repo discovery. --stealth sets no-git-ops: true in
config, disabling all git hook installation and git operations.

This is useful for:
- Non-git VCS (Sapling, Jujutsu, Piper) — no .git/ directory needed
- Monorepos — point BEADS_DIR at a specific subdirectory
- CI/CD — isolated task tracking without repo-level side effects
- Evaluation/testing — ephemeral databases in /tmp

For daemon mode without git, use bd daemon start --local
(see PR #433).

📝 Documentation Copy Chapter

* Documentation site (versioned) | Installing | Agent Workflow | Copilot Setup | Articles | Sync Branch Mode | Troubleshooting | FAQ
*