* feat(schema): never migrate an existing database without explicit consent (bd-qhn8y) Beads 1.2 release remediation. 1.2.0/1.2.1 auto-applied migrations 54-65 at store open on ANY command, including reads; older binaries then refuse the migrated database. MigrateUp now refuses pending main-sequence migrations on an existing database before any write (dolt_ignore seeding included) unless the operator consented: bd migrate / bd migrate schema (preview flags withhold), bd migrate --force, or BD_ALLOW_MIGRATE=1 (BD_ALLOW_REMOTE_MIGRATE honored as an alias). Fresh init and at-latest databases are unaffected; the #4259 remote gate keeps all its protections. Also: freeze shipped migrations (hash-pin test, main 0001-0065 + ignored 0001-0024), retract v1.2.0/v1.2.1 in go.mod, agent-executable un-migrate runbook (docs/recovery/unmigrate-schema-v65.md), and the upgrade smoke + historical migration harnesses now model the consent contract and assert the refusal carries guidance. No version bump here by design: cutting the release stays with the release owner. Rebased onto main800d43eb8d: the go.mod retract hunk is dropped - main already retracts v1.2.0/v1.2.1 (and v1.1.1) since #5782. The uow consent grant moves into the TestMain main added in #6441 (a second TestMain no longer compiles), and the new files are listed in the BUILD.bazel targets main now carries (gazelle). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(schema): cloned-workspace bootstrap carries creation-consent (bd-qhn8y) The consent gate treated a workspace `bd init --remote` / `bd bootstrap` just cloned into existence like a pre-existing database, refusing the smart gate's provably-safe first-mover migration and stranding init in the generic open-error path (bypassing the bd-4mpy7 finalize+guidance ergonomics). Cloning IS creating: those paths now record consent explicitly, and the #4259 remote-migrate gate still applies to them unchanged (consent is not its designated-migrator override). Fixes CI TestEmbeddedInit/remote_behind_schema_gate. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * test(migration): consent first in main's wisp lanes too (bd-qhn8y) The rebase onto800d43eb8dbrought in #6049's wisp-plane lanes, which postdate this PR's harness changes. Each one makes an ordinary candidate command the first touch on an old-schema database, and the consent gate refuses it: - historical-dolt-upgrade-test.sh run_wisp_plane_upgrade opens with `bd list` before any migrate: "candidate could not open the seeded wisp workspace" for v1.0.1, v1.1.0, v1.1.2 and v1.2.2 (the Migration Test Harness dolt-runtime shard). - run_dirty_tracked_wisp_scenario (v1.1.2): the consent refusal stops the open before MigrateUp reaches the #5816 dirty tables, so the lane fails "without naming them". - upgrade-smoke-test.sh "Wisp plane survives upgrade" upgrades with a bare cand_init, so list/ready/blocked/update all hit the refusal (4 failures each for v1.3.0 and v1.3.1, both in the PR smoke set). Use the PR's own pattern: the explicit `bd migrate schema` is the first candidate touch (cand_upgrade in the smoke script). Base800d43eb8dpasses these lanes unchanged; with this fixup the full 14-version historical corpus and all five PR smoke versions pass. Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(schema): close consent-gate review findings (bd-qhn8y) Review fixes for the migration-consent gate (adopt-pr review, attempts 1 and 2). Majors: - #4566 deadlock rebuilt one check earlier: on a database that is both behind and dirty, the consent refusal fired before the dirty-table guard, whose remedy (`bd dolt commit`) opens without consent. The working-set-reconcile opens now tolerate MigrateConsentError: embedded (toleratesConsentRefusal, WSR intent only) and server mode (LenientOpen's warnLenientOpenRefusal) print WorkingSetWarning and commit at the current schema; strict, read-only and RemoteSync opens still refuse. Covered by an embedded test (a refused open writes nothing: dolt_status, dolt_ignore and schema_migrations unchanged) and a server-mode integration subtest. - Bare `bd migrate` consented: isMigrateConsentCommand now matches only the schema verb, so `bd migrate` (metadata reconcile, including --update-repo-id, --inspect and --dry-run) no longer consents to a one-way migration; `bd migrate schema` and --force do. TestLocalMigrateConsentScope pins the scope through the root pre-run. The dirty-table warnings name `bd migrate schema` accordingly. - Runnable JSON hint: the JSON refusal follows the #4259 AgentDirective convention, a non-runnable hint plus a migrate_consent object (versions, pending, severity, human_decision_required, options) whose commands are retargeted with --global for the shared global database. The text refusal prints the same --global hint under `bd --global`. - Freeze floor: the hash-pinned freeze now covers what v1.3.x shipped, main 0001-0066 and ignored 0001-0026; the CHANGELOG puts new migrations in 0070+ / 0028+. - Fresh-bootstrap heal: MigrateUpWithLock with heal authority takes the consent-free migrate path, so a retried bd init whose first pass left a non-zero cursor converges; other lock callers keep the gate. Minors: the uow team-server guards are repinned on `bd migrate schema`; the un-migrate runbook is linked from the recovery index and cross-linked with the 1.2.1 repair-forward doc; the CHANGELOG BREAKING entry matches the shipped contract; harness comment grammar. Docs: the user docs and README named bare `bd migrate` as the step that applies schema migrations; they now say `bd migrate schema`, which also exists in the pinned docs release (v1.2.2) and in v1.3.x. The `bd migrate schema` help no longer claims migrations run automatically on store open. The Go remedy that sends a remote-gate stop to bare `bd migrate` for its migrate-or-adopt options is unchanged (pinned by TestNoticeSharedMigrateRefusalPerDecision). Upgrade smoke (attempt 2): the consent-gate assertion is graded only when the old binary left a database. Releases before v1.0 have no `init --non-interactive`, so prev_init creates nothing there and the candidate's `bd list` fails with "no beads database found", which has no consent guidance. Main's Bazel smoke lane (#7331) runs the newest 30 releases, 20 of them pre-1.0, under the required ci-gate; all 20 went red on the merge. The 10 v1.x releases still take the refusal branch. Shard manifest (pre-approval CI): the new embedded test TestEmbeddedMigrateConsent_BehindAndDirtyWorkingSetReconcileRecovers is listed in the Bazel 15-shard block of embedded-storage-test-shards.txt (incremental --write; shard 15). Main's ci lane runs TestStorageEmbeddedShardManifestGeneratorNotStale in //scripts:scripts_test, which fails on any unlisted top-level embeddeddolt test. Not addressed (optional): env-only consent docs for embedders, the unparseable BD_ALLOW_REMOTE_MIGRATE alias hint, and the harness `|| true` on `cand migrate schema`. Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com> Co-authored-by: Eddie the Engineer <julianknutsen@users.noreply.github.com> Co-authored-by: Eddie the Engineer <adopt-pr@gascity.com>
10 KiB
| title | description |
|---|---|
| Quick Start | Initialize beads, create issues with dependencies, find ready work, and sync with your team in a few minutes |
Get up and running with Beads in a few minutes.
Why Beads?
Flat issue trackers (GitHub Issues, Jira, etc.) show you a list of open items. You pick one. But if that item depends on something else that isn't done yet, you've wasted time. Multiply this across a team of AI agents and humans, and you get thrashing.
Beads tracks dependencies between issues and computes a ready queue — only items with no active blockers appear. Here's the difference:
Flat tracker (GitHub Issues):
Open issues: Set up database, Create API, Add authentication
→ An agent picks "Add authentication" and gets stuck immediately
Beads:
$ bd ready
1. [P1] [task] bd-1: Set up database
$ bd ready --explain --json | jq '.blocked[0]'
{
"id": "bd-3",
"title": "Add authentication",
"blocked_by": [{"id": "bd-2", "title": "Create API", "status": "open"}]
}
The agent picks the right task every time. No wasted cycles.
Installation
Install bd using the full installation guide (Homebrew, install script, npm, or go install).
Developing in a clone of this repository: use make install so the binary gets correct build metadata and a consistent install path. Avoid ad-hoc go build / go install without the Makefile unless you know what you are doing — see the repository README and AGENTS.md.
bd --help
Initialize
First time in a repository:
# Basic setup (prompts for contributor mode)
bd init
# For AI agents (non-interactive)
bd init --quiet
# OSS contributor (fork workflow with separate planning repo)
bd init --contributor
# Team member (branch workflow for collaboration)
bd init --team
# Protected main branch (GitHub/GitLab)
# Note: Dolt stores data under refs/dolt/data, separate from
# Git refs, so no --branch flag is needed.
The wizard will:
- Create
.beads/directory and embedded Dolt database - Prompt for your role (maintainer or contributor) unless a flag is provided
- Import existing issues from git (if any)
- Install git hooks (skip with
--skip-hooks)
Notes:
- Dolt is the default (and only) storage backend. Data is stored in
.beads/embeddeddolt/. - By default, Dolt runs in embedded mode (in-process, no server needed).
- For multi-writer setups, use
bd init --serverto connect to adolt sql-serverinstead. - To import issues from an older installation, run
bd init --from-jsonl.
Role configuration
During bd init, you'll be asked: "Contributing to someone else's repo? [y/N]"
- Answer Y if you're contributing to a fork (runs contributor wizard)
- Answer N if you're the maintainer or have push access
This sets git config beads.role which determines how beads routes issues:
| Role | Use case | Issue storage |
|---|---|---|
maintainer |
Repo owner, team with push access | In-repo .beads/ |
contributor |
Fork contributor, OSS contributor | Separate planning repo |
You can also configure manually:
# Set as contributor
git config beads.role contributor
# Set as maintainer
git config beads.role maintainer
# Check current role
git config --get beads.role
Note: If beads.role is not configured, beads falls back to URL-based detection (deprecated). Run bd doctor to check configuration status.
Your first issues
# Create a few issues
bd create "Set up database" -p 1 -t task
bd create "Create API" -p 2 -t feature
bd create "Add authentication" -p 2 -t feature
# List them
bd list
Note: Issue IDs are hash-based (e.g., bd-a1b2, bd-f14c) to prevent collisions when multiple agents/branches work concurrently.
Hierarchical issues (epics)
For large features, use hierarchical IDs to organize work:
# Create epic (generates parent hash ID)
bd create "Auth System" -t epic -p 1
# Returns: bd-a3f8e9
# Create child tasks (use --parent to attach to the epic)
bd create "Design login UI" -p 1 --parent bd-a3f8e9 # bd-a3f8e9.1
bd create "Backend validation" -p 1 --parent bd-a3f8e9 # bd-a3f8e9.2
bd create "Integration tests" -p 1 --parent bd-a3f8e9 # bd-a3f8e9.3
# View hierarchy
bd dep tree bd-a3f8e9
Output:
Dependency tree for bd-a3f8e9:
> bd-a3f8e9: Auth System [epic] [P1] (open)
> bd-a3f8e9.1: Design login UI [P1] (open)
> bd-a3f8e9.2: Backend validation [P1] (open)
> bd-a3f8e9.3: Integration tests [P1] (open)
Children inherit the epic's labels by default — if the epic carries a size/effort label, see Labels for how to keep it off the children.
Add dependencies
# API depends on database
bd dep add bd-2 bd-1
# Auth depends on API
bd dep add bd-3 bd-2
# View the tree
bd dep tree bd-3
Output:
Dependency tree for bd-3:
> bd-3: Add authentication [P2] (open)
> bd-2: Create API [P2] (open)
> bd-1: Set up database [P1] (open)
Dependency visibility: bd list shows blocking dependencies inline:
○ bd-a1b2 [P1] [task] - Set up database
○ bd-f14c [P2] [feature] - Create API (blocked by: bd-a1b2)
○ bd-g25d [P2] [feature] - Add authentication (blocked by: bd-f14c)
Find ready work
bd ready
Output:
Ready work (1 issues with no active blockers):
1. [P1] bd-1: Set up database
Only bd-1 is ready because bd-2 and bd-3 are blocked.
Understanding why: Use --explain to see the full graph reasoning:
bd ready --explain
Output:
Ready Work Explanation
● Ready (1 issues):
bd-1 [P1] Set up database
Reason: no blocking dependencies
Unblocks: 1 issue(s)
● Blocked (2 issues):
bd-2 [P2] Create API
← blocked by bd-1: Set up database [open]
bd-3 [P2] Add authentication
← blocked by bd-2: Create API [open]
─ Summary: 1 ready, 2 blocked
Note: bd ready is not the same as bd list --status open. The list command shows all open issues regardless of blockers. The ready command computes the dependency graph and only shows truly unblocked work.
Work the queue
# Start working on bd-1
bd update bd-1 --claim
# Complete it
bd close bd-1 --reason "Database setup complete"
# Check ready work again
bd ready
Now bd-2 is ready.
Track progress
# See blocked issues
bd blocked
# View statistics
bd stats
Team sync
Share issues with your team using Dolt remotes. Dolt stores data under refs/dolt/data on the same Git remote, separate from standard Git refs. In repos with origin, bd init configures that Dolt remote automatically.
# Verify the remote, or add one if the repo had no origin during init
bd dolt remote list
bd dolt remote add origin git+ssh://git@github.com/org/repo.git # if needed
# Push your issues
bd dolt push
# Pull teammates' changes
bd dolt pull
When a teammate clones the repo, bd bootstrap auto-detects the existing database on refs/dolt/data, clones it, and wires origin for future bd dolt push / bd dolt pull.
See bd dolt for CLI details. For remote configuration, see Dolt architecture; for federation, see federation.
Optional: Notion sync
If you keep project issues in Notion, supply an integration token first:
export NOTION_TOKEN=<your-token>
# or, if .beads/config.yaml is not tracked by git:
bd config set notion.token <your-token>
bd config set never writes the token to the Dolt database, so bd dolt push does not send it to a remote. It writes the token to .beads/config.yaml instead, and refuses when that file is tracked by git, as it is after bd init in a git repository.
Then either create a new Beads database under a parent page or connect to an existing target:
bd notion init --parent <page-id>
# or
bd notion connect --url <notion-database-or-data-source-url>
Directly setting notion.data_source_id remains available as an escape hatch for advanced setups.
Check which auth source is active and whether the target schema is ready:
bd notion status
bd notion status --json
Preview or run sync:
bd notion sync --dry-run
bd notion sync
bd notion sync --pull
bd notion sync --push
Database location
By default (embedded mode), data is stored in .beads/embeddeddolt/ within your repository.
In server mode, data is managed by the external dolt sql-server.
Migrating databases
After upgrading bd, check for pending database migrations and apply them:
# Inspect migration plan (AI agents)
bd migrate --inspect --json
# Check schema and config
bd info --schema --json
# Preview migration changes
bd migrate --dry-run
# Apply pending schema migrations
bd migrate schema
# Migrate and clean up old files
bd migrate --yes
AI agents: Use --inspect to analyze migration safety before running. The system verifies required config keys and data integrity invariants.
Database maintenance
As your project accumulates closed issues, the database grows. Manage size with these commands:
# View compaction statistics
bd admin compact --stats
# Preview compaction candidates (30+ days closed)
bd admin compact --analyze --json
# Apply agent-generated summary
bd admin compact --apply --id bd-42 --summary summary.txt
# Immediately delete closed issues (CAUTION: permanent!)
bd admin cleanup --force
When to compact:
- Database file > 10MB with many old closed issues
- After major project milestones when old issues are no longer relevant
- Before archiving a project phase
Note: Compaction is permanent graceful decay. Original content is discarded but recoverable via bd restore <id> (from the pre-compaction snapshot, with Dolt history as fallback).
Next steps
- Add labels:
bd create "Task" -l "backend,urgent" - Filter ready work:
bd ready --priority 1 - Explain the graph:
bd ready --explain - Check graph integrity:
bd graph check - Search issues:
bd list --status open - Detect cycles:
bd dep cycles - Gates for PR/CI sync:
bd gate - More sync scenarios:
bd dolt - Full command list: CLI Reference
See the repository README for an overview and links to deeper docs.