beads

Beads (bd)

分散型で、Dolt をバックエンドとする（Git のような）AI コーディングエージェント向けグラフ型課題トラッカーです。依存関係を考慮したタスク管理で、永続的なメモリーを提供します。

クイックスタート

インストール：brew install beads を実行するか、GitHub リポジトリのインストールスクリプトまたはバイナリを使用します。

# Initialize in repo (humans run once)
bd init

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

使用する場面

• AI エージェントがセッションをまたいで永続的なタスクメモリーを必要とする場合
• タスク間の依存関係を追跡する場合（blocks:、depends_on:）
• 複数エージェント／複数ブランチのワークフロー（ハッシュベースの ID により競合を防止）
• 分子／ゲートを使った段階的な提供
• GitLab、Linear、Jira、GitHub と課題を同期する場合

基本コマンド

コマンド	操作
bd ready	未解決のブロッカーがないタスクを一覧表示
bd ready --explain	タスクの準備ができている、またはできていない理由を説明
bd ready --gated	ゲートのチェックポイントで待機中のタスクを表示
bd ready --exclude-type=X	特定の課題タイプを除外
bd create "Title" -p 0	優先度 P0 のタスクを作成
bd show <id>	タスクの詳細と監査履歴を表示
bd update <id> --status=X	ステータスを更新（open/in_progress/done）
bd close <id>	タスクをクローズ
bd close <id> --claim-next	現在のタスクをクローズし、次のタスクを取得
bd dep add <child> <parent>	タスクをリンク（ブロック、関連、親）
bd list	課題を一覧表示（デフォルト：50 件、クローズ済みを除く）
bd list --format json	JSON を出力（--json のエイリアス）
bd show --current	アクティブな課題を表示（ID は不要）
bd update <id> --claim	作業用に課題をアトミックに取得
bd heartbeat <id>	取得したタスクのリースを延長（v1.3.0）
bd reclaim --older-than=10m	期限切れのリースを準備完了状態に戻す（v1.3.0）
bd unclaim <id>	取得したタスクを返却（v1.3.0）
bd update <id> --if-status=S	CAS 更新：ステータスが一致する場合のみ適用
bd note <id> "text"	メモを追記（短縮形）
bd import -i <file>	JSONL を段階的にインポート
bd sync	プル、競合解決、再計算、プッシュ
bd events	永続イベントジャーナルを読み取る（v1.3.0）
bd serve	HTTP API を提供する（v1.3.0）
bd dolt pull	最新の DB 変更をプル（上級者向け）
bd dolt push	DB の変更をプッシュ（上級者向け）
bd bootstrap	ワークスペースの ID を修復／初期化
bd context	現在のワークスペース／タスクのコンテキストを表示
bd kv set <key> <value>	キーと値のペアを保存
bd kv get <key>	保存された値を取得
bd dolt show	Dolt の接続／リモート設定を表示
bd config set-many	複数の設定変更を一度に適用
bd ado sync	Azure DevOps の作業項目と同期
bd ado status	Azure DevOps の同期ステータスを確認
bd ado projects	Azure DevOps のプロジェクトを一覧表示
bd gitlab sync	GitLab と同期
bd github sync	GitHub Issues と同期
bd remember	永続的なエージェントメモリーを書き込む
bd recall	永続的なエージェントメモリーを読み取る
bd purge	クローズ済みの一時的な beads（wisps）を削除

ハッシュベースの ID

課題には、マージ競合を防ぐために bd-a1b2 のようなハッシュベースの ID が使われます。

bd create "Fix login bug" -p 1
# Created: bd-x7k3

bd show bd-x7k3

階層 ID

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

bd children <id> を使用すると、階層を表示できます。

参考資料

ファイル	目的
workflow.md	日常の操作、ステータスの流れ、同期
authoring.md	品質の高い課題の作成、EARS パターン
molecules.md	Molecules、ゲート、数式、化合物
sync.md	Dolt の同期、アップグレード、連携

主な概念

データベースとしての Dolt

Beads は課題を Dolt データベースに保存します。チーム間の同期は、リポジトリの履歴に JSONL ファイルをコミットするのではなく、Dolt 形式の pull／push によって行います。

依存関係グラフ

bd dep add bd-child bd-parent --blocks   # child blocks parent
bd dep add bd-a bd-b --related           # related items
bd ready                                 # only shows unblocked work

Molecules（上級）

Molecules は関連する課題をゲートとともにまとめ、段階的なデリバリーを可能にします。

bd mol create "Feature X" --steps=3      # Create 3-step molecule
bd mol progress bd-xyz                   # Check progress
bd mol burn bd-xyz                       # Complete molecule

ステルスモード

リポジトリにコミットせず、ローカルで Beads を使用します。

bd init --stealth

コントリビューターとメンテナー

# Contributor (forked repos) — separate planning repo
bd init --contributor

# Maintainer auto-detected via SSH/HTTPS credentials

設定

設定は .beads/config.yaml に保存されます。

正確なスキーマはリリースごとに変更されます。現在の設定を確認して検証するには、CLI ヘルパーの使用をおすすめします。

• bd dolt show で現在の Dolt 接続／リモート設定を確認します
• bd dolt test で接続を検証します
• bd doctor ／ bd doctor --deep でヘルスチェックを実行します

ストレージバックエンド（Dolt）

Beads は Dolt をプライマリバックエンドとして使用します。設定に応じて、Dolt は次のモードで実行できます。

• 埋め込み（シングルライター、デーモン不要）
• サーバーモード（マルチライター）

bd doctor（該当する場合は bd doctor --server）を使用して環境を検証します。レガシーストアには、bd migrate のワークフローを使用してください。

エージェント連携

エージェントに Beads を伝える

AGENTS.md に追加します。

## Task Tracking

Use `bd` for task tracking. Run `bd ready` to find work.

エージェント向けに最適化された出力

BD_AGENT_MODE=1 bd list --json  # Ultra-compact JSON output
bd list --json                   # Standard JSON output

MCP プラグイン

Beads には、直接連携するための Claude Code MCP プラグインが含まれています。

リリースの主な内容（1.2.2）

• 復旧リリース：v1.2.0／v1.2.1 はリリーステストを行わずに公開されました。v1.2.2 では、テスト済みの 1.1 系をより高いバージョンで再リリースし、すべてのインストール経路でテスト済みのコードに移行します。1.2.x のみの機能（作業リース、イベントジャーナル、同期フェデレーション、HTTP API サーバー、プロベナンスイベント）は、このリリースには含まれません。これらは、テスト済みの将来のリリースで再び提供されます。
• v1.2.1 を実行していて schema version mismatch: database is at v65, binary knows up to v53 が発生した場合は、スキーマカーソルを v53 に戻す（docs/RECOVERY-1.2.1.md を参照）か、暫定措置として BD_IGNORE_SCHEMA_SKEW=1 を使用してください。詳しくは references/sync.md を参照してください。復旧する前に、すべてのマシン／クローンを v1.2.2 にアップグレードしてください。古い 1.2.1 バイナリが残っていると、データベースが知らないうちに再移行されます。

リリースの主な内容（1.1.0）

• より安全な移行：スキーマ変更を検出することで、データベース移行が通知なく適用されないようにし、すべてのレイヤーで読み取り専用を強制します。
• 同期の修復：これまで問題のあったプルのマージを修復し、情報を破棄する前にコンパクションでアーカイブするようになりました。
• 新しいコマンド／フラグ：bd metrics（同意通知付き）と、冪等な --init-if-missing 初期化を追加しました。

リリースの主な内容（1.0.3–1.0.4）

• ワークフロー／設定の使いやすさ：bd -C で実行前に作業ディレクトリを変更できるようになりました。bd close に --reason-file が追加され、セットアップ／ブートストラップのフローでリモート／サーバー設定の処理が改善されました。
• Linear 同期：OAuth クライアントクレデンシャル、冪等性マーカー、古いデータの通知、ワークスペースごとの同期ロック、より豊富なタイプマッピング、バッチ作成／更新により、大規模な同期ループの安全性と速度が向上しました。
• セキュリティ／エクスポートの既定値：Beads は、Git で追跡される設定ファイルへの秘密鍵の書き込みを拒否するようになりました。また、明示的に有効に戻さない限り、エクスポートからメモリーと一時的な wisps を除外します。
• 依存関係／データパス：JSONL による一括依存関係の追加や、いくつかのフック／ブートストラップ／初期化の修正により、自動化環境や共有サーバー環境での手間が軽減されました。

リリースの主な変更点（1.0.0–1.0.2）

• 配布：プリコンパイル済みバイナリが Linux、macOS（Intel／Apple Silicon）、Windows（AMD64／ARM64）、Android／Termux、FreeBSD に対応しました。
• 自動化：bd init --non-interactive／--role と bd bootstrap --non-interactive により、CI／クラウドエージェントのセットアップが改善されました。
• ワークフロー：bd ready --explain、bd config set-many、依存関係の一括一覧表示、カンマ区切りのステータスフィルターにより、エージェントの使い勝手が向上しました。
• 作成／モデリング：spike、story、milestone が正式なイシュータイプになりました。カスタムステータス／タイプは正規化テーブルに移行しました。
• 連携／同期：GitLab 同期で重複排除と epic から milestone へのマッピングが改善され、ADO 同期ではより多くのフィルターが適用されるようになりました。また、組み込み／共有サーバーの復旧がより安全になりました。

リリースの主な変更点（0.62.0–0.63.3）

• Azure DevOps 連携：作業項目の追跡用に bd ado CLI コマンド（同期、ステータス、プロジェクト）が追加されました。
• 組み込み Dolt 対応：Dolt サーバーを起動していなくても、dep、duplicate、epic、graph、supersede、swarm の各操作を利用できます。
• カスタムステータスカテゴリ：active／wip／done／frozen のステータス分類を設定できます。
• bd note コマンド：イシューにメモを追記するための短縮コマンドです。
• --exclude-type フラグ：bd ready と bd list でイシュータイプによる絞り込みができます。
• --format json エイリアス：一貫性を保つため、--json フラグの代替として利用できます。
• 監査ログ：クローズ理由を記録し、ステータス変更を interactions.jsonl に記録します。
• エクスポート／インポートでのメモリ：エージェントのメモリも往復処理の対象になります。
• init のデフォルト設定：AGENTS.md は最小限のプロファイルがデフォルトになり、--agents-profile フラグが追加されました。
• 品質／ライフサイクルコマンド：prime、template、doctor で利用できるようになりました。
• クローズ時の検証：--validate で --acceptance フィールドをチェックでき、validation.on-close 設定も追加されました。

リリースの主な変更点（0.61.0）

• bd close --claim-next により、エージェントがよく使うクローズして次のイシューを取得する一連の操作を短縮できます。
• bd create に --skills、--context、--no-history が追加され、より詳細なタスク作成と、必要に応じた Dolt 履歴の記録抑制が可能になりました。
• bd import にポータビリティと復旧ワークフロー向けの、JSONL の差分インポートが追加されました。
• bd init／bd bootstrap で、リポジトリの git origin から Beads データベースを自動検出できるようになりました。
• Dolt／サーバーモードの同期で、認証情報の引き継ぎ、実行時のポート報告、ヘルスチェックが改善されました。
• プロジェクト設定とユーザー設定の適切なマージや、BD_BACKUP_ENABLED=false のサポートなどにより、設定とバックアップの処理がより安全になりました。

重要なコマンド

# What to work on
bd ready                    # Unblocked tasks
bd ready --pretty           # Formatted output

# Create with dependencies
bd create "Task B" --blocks bd-a1b2
bd create "Task C" --context "Need schema review" --skills "python,sql"

# Doctor (fix issues)
bd doctor                   # Check health
bd doctor --fix             # Auto-fix problems

bd sync                     # Sync DB state
bd import -i backup.jsonl   # Incremental JSONL import

bd dolt pull                # Pull latest changes (advanced)
bd dolt push                # Push to remote (advanced)

アンチパターン

❌ 誤り	✅ 正しい方法
priority: high	-p 1（P0-P4 の数値）
JSON を手動で編集する	bd コマンドを使う
bd ready を無視する	まず必ずブロッカーを確認する
bd sync を省略する	作業の前後に同期する
依存関係を指定せずに作成する	事前に --blocks を宣言する

リンク

• リリース
• ドキュメント
• コミュニティツール