How do I install beads?

Run these in Claude Code: /plugin marketplace add gastownhall/beads then /plugin install beads@beads-marketplace. Then prompt normally.

Does beads auto-invoke its skills?

Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.

Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.

Development

Plugin

beads

Distributed graph issue tracker for AI agents, powered by Dolt. Platforms: macOS, Linux, Windows, FreeBSD Docs: Beads provides a persistent, structured memory for coding agents.

FLOW.md

gastownhall@gastownhall

GitHub

Plugin Signal92/100Strong

maintained100

capable75

documented100

adopted94

Install on Claude Code

> /plugin marketplace add gastownhall/beads
> /plugin install beads@beads-marketplace

Stats

JavaScript Node Bash SQL Linux

+7 tags

Git GitHub CI/CD Markdown Mermaid Anthropic MCP

26,163

Stars

1,750

Forks

Active

Maintenance

Language

MIT

License

2m ago

Last commit

10mo ago

Created

Repo: gastownhall/beads

What's inside

Show all 29 commands

/createCreate a new issue interactively /decisionRecord, list, and manage project decisions with rationale tracking /deleteDelete issues and clean up references /depManage dependencies between issues /epicEpic management commands /exportExport issues to JSONL format /importImport issues and memories from JSONL /initInitialize beads in the current project /labelManage issue labels /listList issues with optional filters /primeLoad AI-optimized workflow context for beads issue tracking./quickstartQuick start guide for bd workflows (deprecated)/readyFind ready-to-work tasks with no blockers /rename-prefixRename the issue prefix for all issues /reopenReopen closed issues /restoreRestore full history of compacted issue from git /searchSearch issues by text query /showShow detailed information about an issue /statsShow project statistics and progress /syncSynchronize issues with a configured Dolt remote /updateUpdate an issue's status, priority, or other fields /versionCheck beads and plugin versions /workflowShow the AI-supervised issue workflow guide

README

Read on GitHub

bd - Beads

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

Platforms: macOS, Linux, Windows, FreeBSD

Docs: https://beads.gascity.com/

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.

flowchart LR
    create["bd create<br/>new bead"] --> depgraph["dependency<br/>graph"]
    depgraph --> ready["bd ready<br/>claimable work"]
    ready --> claim["bd update --claim<br/>agent takes it"]
    claim --> close["bd close<br/>work done"]
    close -->|blockers released| ready
    depgraph <-->|"bd dolt push / pull"| remote[("other machines<br/>and agents")]

⚡ Quick Start

# Install beads CLI (system-wide - don't clone this repo into your project)
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash

# Initialize in YOUR project
cd your-project
bd init

# Optional: refresh or install richer instructions for your agent
bd setup codex    # Codex CLI - installs skill, AGENTS.md guidance, and hooks
bd setup claude   # Claude Code - installs hooks/settings
bd setup factory  # Factory.ai Droid - creates/updates 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.

bd init creates or updates AGENTS.md by default so agents can discover the beads workflow, and also installs project Claude/Codex integrations unless you pass --skip-agents or --stealth. Use bd setup --list to see supported integrations, including bd setup codex, bd setup factory, bd setup claude, bd setup mux, bd setup cursor, and more. See Agent and IDE setup.

Manual copy-paste is only for unsupported agents, existing projects where you cannot rerun bd init/bd setup, or custom instruction files. In those cases, run bd onboard and paste the printed snippet into the file your agent reads.

If your agent is not covered by bd setup, add this minimal AGENTS.md section:

This project uses bd (beads) for issue tracking.

- Run `bd prime` for workflow context and command guidance.
- Use `bd ready`, `bd show <id>`, `bd update <id> --claim`, and `bd close <id>`.
- Use `bd remember "insight"` for persistent project memory; do not create MEMORY.md files.
- Do not use markdown TODO lists for task tracking.

🛠 Features

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

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.
`bd prime`	Print agent workflow context and persistent memories.
`bd remember "insight"`	Store project memory that `bd prime` injects later.

🔗 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. 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

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/getting-started/installation.md for complete installation guide.

Upgrading? Replacing the binary is not always the whole story. Short version: sync remote-backed databases with your current bd, back up with bd export --all, upgrade the binary, then run bd info --whats-new, bd hooks install, and bd version. If the upgrade crosses a schema migration on a remote-backed database, exactly one designated clone runs bd migrate and bd dolt push; other clones install the new binary and run bd bootstrap. See the full upgrade guide or docs/getting-started/installation.md.

Security And Verification

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/reference/antivirus.md for Windows AV false-positive guidance and verification workflow.

💾 Storage Modes

Beads uses Dolt as its database. Two modes:

Embedded (default) — bd init. Dolt runs in-process, data lives in .beads/embeddeddolt/, single writer. Recommended for most users.
Server — bd init --server. Connects to an external dolt sql-server for multiple concurrent writers; data lives in .beads/dolt/.

Cross-machine sync uses bd dolt push / bd dolt pull against refs/dolt/data on your git remote; .beads/issues.jsonl is an export for viewers and interchange, not the source of truth or a backup. Back up and migrate between modes with bd backup; reclaim space with bd prune / bd purge.

Full detail — connection flags, sockets, maintenance, backup, and migration — in the Dolt backend guide.

Schema Version Guard

bd checks the database schema version at open time. If the database has been migrated by a newer binary and an older binary tries to open it, bd exits with an actionable error rather than issuing queries that fail with cryptic SQL errors:

schema version mismatch: database is at v45, binary knows up to v42 (3 migrations ahead)

  Your bd binary is stale. Queries for dropped or renamed columns will fail
  with cryptic SQL errors (e.g. "column X could not be found in any table in scope").

  Rebuild from main:
    CGO_ENABLED=0 go build -tags gms_pure_go ./cmd/bd

  Or install the latest release:
    CGO_ENABLED=0 go install -tags gms_pure_go github.com/steveyegge/beads/cmd/bd@latest

  To proceed despite the risk (some read commands may still work):
    BD_IGNORE_SCHEMA_SKEW=1 bd <command>
    bd --ignore-schema-skew <command>

When this fires: only when the database schema is ahead of the binary (a newer binary migrated the database; this binary doesn't know those migrations). Normal upgrades, where the binary migrates the database forward, are unaffected.

Escape hatch: BD_IGNORE_SCHEMA_SKEW=1 (or --ignore-schema-skew) bypasses the guard with a warning on stderr. Use this only if you know the forward migrations are additive and safe for your specific workload.

🌐 Community Tools

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.

See docs/related-projects.md for adjacent or complementary projects that solve different problems in the same neighborhood.

🚀 Git-Free Usage

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

📝 Documentation

Documentation site | Installing | Sync Concepts | Agent Workflow | Copilot CLI Setup | Copilot VS Code MCP | Articles | Sync Branch Mode | Troubleshooting | FAQ

File tree

1893

gastownhall/beadsView on GitHub

.agent/
  workflows/
    resolve-beads-conflict.md
.beads/
  formulas/
    beads-release.formula.toml
.buildflags
.claude/
.claude-plugin/
  marketplace.json
  hooks/
    block-gh-watch.sh
    block-interactive-cmds.sh
  settings.json
  skills/
    beads-docs/
      references/
        simplification.md
        terminology.md
        verification.md
      SKILL.md
  test-strategy.md
.devcontainer/
  devcontainer.json
  README.md
  setup.sh
.gitattributes
.githooks/
  post-checkout
  post-merge
  pre-commit
  pre-push
  prepare-commit-msg
.github/
  CODEOWNERS
  copilot-instructions.md
  dependabot.yml
  images/
    agent-using-beads.jpg
  pages-redirect/
    index.html
  PULL_REQUEST_TEMPLATE.md
  scripts/
    ci-capability-selector.sh
    ci-embedded-tier.sh
    ci-gate.sh
    docs-render-check.sh
    embedded-cmd-test-shards.txt
    embedded-storage-test-shard.sh
    embedded-storage-test-shards.txt
    embedded-test-shard.sh
    proxied-cmd-test-shards.txt
    proxied-test-shard.sh
  workflows/
    ci-measurements.yml
    conformance.yml
    cross-version-smoke.yml
    deploy-pages-redirect.yml
    docs-autofix.yml
    docs-mintlify.yml
    main.yml
    migration-test.yml
    nightly.yml
    nix-build.yml
    pr-risk.yml
    pr.yml
    proxied-local-smoke.yml
    regression.yml
    release.yml
    test-pypi.yml
    update-flake-lock.yml
    update-vendor-hash.yml
.gitignore
.golangci.yml
.goreleaser.yml
.pre-commit-config.yaml
.test-skip
AGENT_INSTRUCTIONS.md
AGENTS.md
ARTICLES.md
backend/
  backend.go
  completeness_test.go
  conformance/
    audit_config_metadata_slots_repomtime.go
    audit_dependencies_readiness.go
    audit_issue-lifecycle.go
    audit_labels-comments-events.go
    audit_molecule_wisp_batch_iter.go
    audit_search-counts-stats.go
    audit.go
    batch_apply_contract.go
    batch_closer_contract.go
    batch_creator_contract.go
    blocked_state.go
    blocking_annotator_contract.go
    bootstrapper_contract.go
    claim.go
    claimer_contract.go
    commenter_contract.go
    conformance.go
    counter_contract.go
    cycle_detector_contract.go
    deleter_contract.go
    dependency_editor_contract.go
    edge_reader_contract.go
    graph_counter_contract.go
    history_matching.go
    importer_contract.go
    issue_operations_contract.go
    issue_operations_staging.go
    lifecycle_close_reopen_contract.go
    lifecycle_create_contract.go
    lifecycle_update_contract.go
    memories_contract.go
    metadata_cas_contract.go
    portable.go
    querier_contract.go
    reader_contract.go
    ready_claimer_contract.go
    ready_counter_contract.go
    reclaim_scope.go
    relations_contract.go
    releaser_contract.go
    role_bundle_cases.go
    role_bundle_test.go
    role_bundle.go
    role_coverage_gate_test.go
    role_coverage_scan_test.go
    search_paging.go
    stats_reporter_contract.go
    sweeper_contract.go
    tree_walker_contract.go
    version_reconciler_contract.go
    workspaceconfig_contract.go
  errors_test.go
  errors.go
  types.go
beads_cgo.go
beads_gated_test.go
beads_nocgo.go
beads_test.go
beads.go
beadserrors/
  errors.go
BENCHMARKS.md
build-docs.md
CHANGELOG.md
claim_roundtrip_test.go
claim_test.go
claim.go
CLAUDE.md
cmd/
  bd/
    actor_test.go
    admin.go
    ado_roundtrip_test.go
    ado_test.go
    ado.go
    agent_hook.go
    AGENTS.md
    assign_fence_embedded_test.go
    assign_fence_proxied_test.go
    assign.go
    audit.go
    auto_import_upgrade_test.go
    auto_import_upgrade_unit_test.go
    auto_import_upgrade.go
    autocommit_embedded_test.go
    backend_registry_contract_test.go
    backend_support.go
    backup_auto_test.go
    backup_auto.go
    backup_dolt_test.go
    backup_dolt.go
    backup_embedded_test.go
    backup_export_failure_test.go
    backup_export.go
    backup_restore_test.go
    backup_restore.go
    backup_status_test.go
    backup_test.go
    backup.go
    batch_embedded_test.go
    batch_parity_test.go
    batch_proxied_server.go
    batch_test.go
    batch.go
    blocked_embedded_test.go
    blocked_proxied_integration_test.go
    bootstrap_backend_guard_test.go
    bootstrap_embedded_test.go
    bootstrap_guard_test.go
    bootstrap_noninteractive_test.go
    bootstrap_registered_backend_test.go
    bootstrap_test.go
    bootstrap_worktree_test.go
    bootstrap.go
    branch_embedded_test.go
    branch.go
    cascade_parity_proxied_integration_test.go
    children_embedded_test.go
    children_test.go
    children.go
    claim_pools_embedded_test.go
    cleanup.go
    cli_coverage_show_test.go
    cli_fast_test.go
    close_direct.go
    close_embedded_test.go
    close_gate_test.go
    close_last_touched_test.go
    close_proxied_integration_test.go
    close_proxied_server.go
    close_reason_file_test.go
    close_routing_test.go
    close.go
    closed_delete_candidates.go
    codex_hook_test.go
    codex_hook.go
    command_telemetry_test.go
    command_telemetry.go
    comment_promote_embedded_test.go
    comment_proxied_integration_test.go
    comment_test.go
    comment.go
    comments_cli_embedded_test.go
    comments_proxied_server.go
    comments_test.go
    comments.go
    compact_dolt_proxied_server.go
    compact_dolt.go
    compact_embedded_test.go
    compact_gc_flag_test.go
    compact_proxied_server.go
    compact_test.go
    compact_tier2_embedded_test.go
    compact.go
    completions_test.go
    completions.go
    config_apply_test.go
    config_apply.go
    config_drift_test.go
    config_drift_unix.go
    config_drift_windows_test.go
    config_drift_windows.go
    config_drift.go
    config_embedded_test.go
    config_get_backup_enabled_embedded_test.go
    config_get_backup_enabled_test.go
    config_guard_test.go
    config_isolation_regression_test.go
    config_list_test.go
    config_nodb_embedded_test.go
    config_proxied_integration_test.go
    config_proxied_server.go
    config_setmany_test.go
    config_show_kv_exclusion_test.go
    config_show_test.go
    config_show.go
    config_side_effects_test.go
    config_side_effects.go
    config_test.go
    config_validate_key_test.go
    config_worktree_test.go
    config.go
    conflicts_conclude_integration_test.go
    conflicts_conclude_test.go
    conflicts_test.go
    conflicts.go
    context_binding_integration_test.go
    context_binding_test.go
    context_cmd_test.go
    context_cmd.go
    context_embedded_test.go
    context_identity_test.go
    context_proxied_integration_test.go
    context_proxied_server.go
    context_test.go
    context.go
    contributor_embedded_test.go
    contributor_routing_e2e_test.go
    cook_qnt_test.go
    cook_test.go
    cook.go
    count_embedded_test.go
    count_filter_test.go
    count_proxied_integration_test.go
    count_proxied_server.go
    count.go
    cpu_profile_test.go
    create_atomic_test.go
    create_atomic.go
    create_deps_atomic_test.go
    create_deps_test.go
    create_deps.go
    create_dispatch_test.go
    create_embedded_test.go
    create_external_ref_test.go
    create_form_test.go
    create_form.go
    create_input_test.go
    create_input.go
    create_labels_test.go
    create_markdown_batch_test.go
    create_notes_test.go
    create_prefix_test.go
    create_proxied_external_integration_test.go
    create_proxied_integration_test.go
    create_proxied_server_test.go
    create_proxied_server.go
    create_repo_no_cwd_beads_embedded_test.go
    create_repo_remote_url_preprun_test.go
    create_routing_test.go
    create_test.go
    create.go
    critical_paths_test.go
    cross_mode_parity_harness_test.go
    cursor_hook_test.go
    cursor_hook.go
    database_name_test.go
    database_name.go
    db_proxy_child_test.go
    db_proxy_child.go
    defer_embedded_test.go
    defer_proxied_integration_test.go
    defer_proxied_server.go
    defer_wake_embedded_test.go
    defer_wake_proxied_integration_test.go
    defer.go
    delete_embedded_test.go
    delete_input_test.go
    delete_proxied_integration_test.go
    delete_proxied_server_output_test.go
    delete_proxied_server.go
    delete_test.go
    delete.go
    dep_batch_test.go
    dep_bulk_role_test.go
    dep_cycles_test.go
    dep_cycles.go
    dep_edge_reader_test.go
    dep_embedded_test.go
    dep_proxied_integration_test.go
    dep_proxied_server.go
    dep_test.go
    dep_tree.go
    dep.go
    dependency_hierarchy_embedded_test.go
    dependency_hierarchy_test.go
    detect_pollution.go
    diff_embedded_test.go
    diff.go
    direct_mode.go
    directory_flag_test.go
    docs.md
    doctor/
    doctor_agent.go
    doctor_artifacts.go
    doctor_backend_guard_test.go
    doctor_context_test.go
    doctor_conventions_test.go
    doctor_conventions.go
    doctor_embedded_test.go
    doctor_fix_order_test.go
    doctor_fix_pending_migrations_test.go
    doctor_fix.go
    doctor_gastown_guard_test.go
    doctor_gastown_guard.go
    doctor_health_integration_test.go
    doctor_health_smoke_test.go
    doctor_health_test.go
    doctor_health.go
    doctor_init_diagnostics_cgo_test.go
    doctor_max_rows_test.go
    doctor_migrate_fix_test.go
    doctor_pollution.go
    doctor_repair_chaos_test.go
    doctor_repair_test.go
    doctor_test.go
    doctor_validate_test.go
    doctor_validate.go
    doctor.go
      agent_test.go
      agent.go
      artifacts_test.go
      artifacts.go
      backend.go
      bare_parent_fallback_test.go
      blocked.go
      circuit.go
      claude_test.go
      claude.go
      clone_local_fks.go
      config_values_test.go
      config_values.go
      cross_table.go
      cursor_test.go
      cursor.go
      database_test.go
... 1600 more

Showing a partial view of a very large repo.

FAQ

beads is a Claude Code plugin with 3 hand-picked skills for development work, indexed on Flowy. Install it with the command on its page. It includes beads-docs, beads, beads. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.

What is beads?: Distributed graph issue tracker for AI agents, powered by Dolt. Platforms: macOS, Linux, Windows, FreeBSD Docs: Beads provides a persistent, structured memory for coding agents.
How do I install beads?: Run these in Claude Code: /plugin marketplace add gastownhall/beads then /plugin install beads@beads-marketplace. Then prompt normally.
Does beads auto-invoke its skills?: Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.
Is beads free?: Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.