Beads - A memory upgrade for your coding agent https://beads.gascity.com
  • Go 95.2%
  • Python 1.6%
  • Starlark 1.5%
  • Shell 1.3%
  • Rust 0.2%
Find a file
Doug Campos eff58e494c feat: add no-push config to disable automatic git push
Wire up the existing --no-push flag to a config option so it can be
set as the default, and update bd prime output accordingly.

- Add no-push default to config.go, matching existing pattern
- Check config in sync.go when --no-push flag not explicitly set
- Update bd prime output to omit git push step when enabled
2025-12-18 00:49:07 -05:00
.agent/workflows fix: improve JSONL-only mode detection and error messages (GH #534) 2025-12-13 12:50:33 -08:00
.beads chore: Clean up old closed issues and tombstones 2025-12-17 16:13:43 -08:00
.beads-hooks Merge GH#532 2025-12-16 01:19:14 -08:00
.claude feat: Add test infrastructure with automatic skip list 2025-11-21 22:43:04 -05:00
.claude-plugin fix: Update remaining version files to 0.30.3 2025-12-17 19:58:47 -08:00
.devcontainer Fix devcontainer init check - look for DB file not directory 2025-11-05 17:31:30 -08:00
.github fix: Update npm publish to use OIDC trusted publishing 2025-12-17 19:51:10 -08:00
cmd/bd feat: add no-push config to disable automatic git push 2025-12-18 00:49:07 -05:00
commands fix(docs): use consistent in_progress status naming (GH#444) 2025-12-16 01:07:33 -08:00
docs feat: add no-push config to disable automatic git push 2025-12-18 00:49:07 -05:00
examples Update link to EXTENDING.md in example extending README 2025-12-16 16:46:25 -08:00
integrations/beads-mcp fix: Update remaining version files to 0.30.3 2025-12-17 19:58:47 -08:00
internal feat: add no-push config to disable automatic git push 2025-12-18 00:49:07 -05:00
lib Add Python cache files to .gitignore 2025-11-08 02:42:53 -08:00
npm-package fix: Update npm package version to 0.30.3 2025-12-17 19:22:35 -08:00
scripts fix: sync all version files to 0.30.2 and add CI check 2025-12-16 17:13:01 -08:00
skills/beads docs: update beads.jsonl references to issues.jsonl 2025-12-16 01:08:46 -08:00
tests Add comprehensive Agent Mail coordination tests (bd-pdjb) 2025-11-08 02:48:05 -08:00
.gitattributes bd-6xd: Standardize on issues.jsonl as canonical filename 2025-11-26 22:02:59 -08:00
.gitignore feat: add Git worktree compatibility (PR #478) 2025-12-13 12:50:33 -08:00
.golangci.yml fix: resolve CI lint errors and Windows test timeout 2025-12-03 17:50:23 -08:00
.goreleaser.yml fix: Add commit and branch to bd version output (github #503) 2025-12-13 10:04:01 +11:00
.test-skip Remove TestFallbackToDirectModeEnablesFlush from test skip list 2025-11-23 16:05:28 -08:00
AGENT_INSTRUCTIONS.md fix: improve JSONL-only mode detection and error messages (GH #534) 2025-12-13 12:50:33 -08:00
AGENTS.md feat: complete bd-kwro messaging & knowledge graph epic 2025-12-16 20:36:47 -08:00
beads.go Export Transaction type for atomic multi-operation support 2025-11-24 22:55:55 -08:00
beads_test.go bd-6xd: Standardize on issues.jsonl as canonical filename 2025-11-26 22:02:59 -08:00
BENCHMARKS.md feat(cli): add 'bd thanks' command to thank contributors 2025-12-14 12:40:32 -08:00
build-docs.md docs: Add comprehensive documentation for version reporting changes 2025-12-13 10:04:01 +11:00
CHANGELOG.md chore: Bump version to 0.30.3 2025-12-17 19:16:12 -08:00
CLAUDE.md docs: update beads refinery CLAUDE.md with new terminology 2025-12-05 14:22:38 -08:00
CONTRIBUTING.md ci: add check to reject PRs with .beads/issues.jsonl changes 2025-12-15 23:43:30 -08:00
default.nix chore: bump version to 0.30.2 2025-12-16 16:47:43 -08:00
flake.lock feat: Add Nix flake for declarative builds 2025-10-15 13:45:05 +02:00
flake.nix fix: NixOS symlink compatibility for mtime and permission checks (#459) 2025-12-05 13:22:09 -08:00
go.mod add visual create-form command 2025-12-16 17:05:45 -08:00
go.sum add visual create-form command 2025-12-16 17:05:45 -08:00
install.ps1 docs: don't auto-install Go in Windows installer; instruct user instead (fixes #292) (#302) 2025-11-12 14:15:46 -08:00
LICENSE Initial commit: Beads issue tracker with security fixes 2025-10-11 20:07:36 -07:00
Makefile fix: Add commit and branch to bd version output (github #503) 2025-12-13 10:04:01 +11:00
README.md docs: restore Community Tools section with beads.el 2025-12-17 13:45:41 -08:00
RELEASING.md Add --upgrade-mcp flag to bump-version.sh 2025-11-23 22:25:37 -08:00
SECURITY.md Prepare for public launch: comprehensive examples, docs, and tooling 2025-10-12 11:25:29 -07:00

bd - Beads

Distributed, git-backed graph issue tracker for AI agents.

License Go Report Card Release npm version PyPI

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

# Install (macOS/Linux)
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

# Initialize (Humans run this once)
bd init

# Tell your agent
echo "Use 'bd' for task tracking" >> AGENTS.md

🛠 Features

  • Git as Database: Issues stored as JSONL in .beads/. Versioned, branched, and merged like code.
  • 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.
  • Invisible Infrastructure: SQLite local cache for speed; background daemon for auto-sync.
  • Compaction: Semantic "memory decay" summarizes old closed tasks to save context window.

📖 Essential Commands

Command Action
bd ready List tasks with no open blockers.
bd create "Title" -p 0 Create a P0 task.
bd dep add <child> <parent> Link tasks (blocks, related, parent-child).
bd show <id> View task details and audit trail.
bd quickstart Interactive guide for AI agents.

🔗 Hierarchy & Workflow

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.

📦 Installation

  • npm: npm install -g @beads/bd
  • Homebrew: brew install steveyegge/beads/bd
  • Go: go install github.com/steveyegge/beads/cmd/bd@latest

Requirements: Linux (glibc 2.32+), macOS, or Windows.

🌐 Community Tools

  • beads_viewer - Keyboard-driven terminal UI with kanban board, insights panel, and graph view. Built by @Dicklesworthstone.
  • beads.el - Emacs UI to browse, edit, and manage beads. Built by @ctietze.
  • beads-ui - Local web interface with live updates and kanban board. npx beads-ui start. Built by @mantoni.
  • bdui - Real-time terminal UI with tree view, dependency graph, and vim-style navigation. Built by @assimelha.
  • perles - Terminal UI with BQL (Beads Query Language) and multi-view kanban. Built by @zjrosen.
  • vscode-beads - VS Code extension with issues panel and daemon management. Built by @jdillon.

📝 Documentation