使ったことのあるイシュートラッカーはすべて同じパターンに従う。クラウドサービスがある。Web UIがある。誰かがクラウドAPIと通信するCLIを構築する。CLIは二級市民だ: 遅く、機能が少なく、常にAPIバージョンが1つ遅れている。

そのアーキテクチャをひっくり返す。CLIから始める。ローカルデータベースに書き込ませる。データベースにバージョン管理を持たせ、ソースコードに使うのと同じブランチとマージのセマンティクスにする。そしてその上に、同じデータベースファイルを直接読むネイティブデスクトップアプリを置く。APIは介在しない。

それがbeadsとBeadboxだ。そしてこのアーキテクチャが存在する理由はAIエージェントだ。

問題: エージェントはボタンをクリックできない

AIエージェントのフリート(コードジェネレーター、レビュアー、テスター、デプロイヤー)をコーディネートしているなら、エージェントにイシューの作成、ステータスの更新、ワークキューの読み取りが必要だ。Jiraに認証できない。LinearのUIをナビゲートできない。ローカルデータベースに書き込むCLIが必要で、高速で、ネットワーク依存ゼロでなければならない。

beadsがそのCLIだ。まさにこのワークフローのために設計された、オープンソースのGitネイティブイシュートラッカーだ。bdコマンドでイシューの作成、更新、一覧表示、クローズを行う。すべての書き込みはリポジトリの.beads/ディレクトリ内のローカルDoltデータベースに記録される。

数字が重要だ。bd createは約15msかかる。1万件のイシューに対するbd listは約200msで返る。これらのベンチマークはbeadsテストスイートから来ている。エージェントがタイトなループで作業項目を消化しているとき、操作あたりのミリ秒がイシュートラッカーが追いつくかボトルネックになるかを決定する。

なぜSQLiteではなくDoltか?

Doltは、Gitセマンティクスを実装したSQLデータベースだ。すべての書き込みがコミットになる。dolt diffで2つの時点間の変更を確認できる。dolt logで完全な監査履歴が得られる。dolt branchとdolt mergeが、コードに対してすでに使っているのと同じメンタルモデルで使える。

イシュートラッキングにとって、これはプロジェクト履歴が2つの並行する監査証跡を持つことを意味する: コード変更のgit logと、イシュー変更のdolt log。「v2.1.0をタグ付けしたとき、イシューデータベースはどんな状態だったか?」という質問に、Dolt履歴のその時点をチェックアウトすることで答えられる。イシューデータベースをブランチして再構成を試み、マージバックするか捨てるかできる。

beadsはv0.9.0でSQLiteサポートを廃止し、Doltに全面移行した。バージョン管理セマンティクスはあったらいい機能ではなく、基盤だ。20体のエージェントが同じイシューデータベースに書き込んでいるとき、ソースコントロールに対して持っているのと同じ自信で、そのデータをdiff、ブランチ、マージできる能力が欲しい。

オプションのコラボレーションはDoltHubを通じて機能する。イシューデータベースをリモートにプッシュし、チームメイトから変更をプルする。Gitと同じプッシュ/プルワークフローが、構造化データに適用される。

ビジュアル層: Beadbox

エージェントはCLIで力を発揮する。人間は、少なくとも全体像が必要なときはそうではない。依存関係グラフ、エピック進捗ツリー、ブロックされたイシューチェーン: これらはターミナルではうまくレンダリングできない空間的な問題だ。

Beadboxは、Tauri(Electronではない)で構築されたネイティブデスクトップアプリケーションで、CLIが書き込むのと同じ.beads/ディレクトリを読む。インポート手順も同期プロセスもAPI層もない。GUIはfs.watch()でファイルシステムを監視し、Doltデータベースの変更を検出し、ローカルWebSocket経由で更新をブロードキャストする。エージェントがbd update BEAD-42 --status in_progressを実行すると、Beadboxのステータスバッジがミリ秒以内に変わる。

実際のワークフローはこうなる:

# エージェントがイシューを作成
bd create --title "Migrate auth to OIDC" --type task --priority 1

# 別のエージェントが担当
bd update BEAD-42 --claim --actor agent-3

# 人間がBeadboxを開いてボード全体を見る:
# 依存関係グラフ、エピックツリー、ステータス/優先度/担当者でフィルタ
# コマンド不要。見るだけ。

# エージェントが完了してレビュー待ちにする
bd update BEAD-42 --status ready_for_qa

# Beadboxがリアルタイムで更新。QAエージェントがピックアップ。

エージェントはCLI経由で書き込む。人間はGUI経由で読む。どちらも同じローカルDoltデータベースで操作する。調整なし、古いキャッシュなし、「リフレッシュさせて」なし。

Beadboxはmac OS、Linux、Windowsで動作する。複数のワークスペースをサポートし、再起動なしでプロジェクトを切り替えられる。

「ローカルファースト」の本当の意味

この用語は使い古されている。beadsとBeadboxにとって具体的に何を意味するか:

アカウント不要。 何にもサインアップしない。CLIをインストールし、アプリをインストールし、ディレクトリを指定する。以上。

クラウド依存なし。 すべてがファイルシステム上で動く。明示的にリモートにdolt pushしない限り、データはマシンから出ない。インターネットが落ちても何も変わらない。作業を続けるだけだ。

サーバー不要。 管理するデーモンもDockerコンテナもない。Doltデータベースはファイルのディレクトリだ。CLIがそのファイルを読み書きする。Beadboxがそのファイルを監視する。

オプションのコラボレーション。 共有したいときは、DoltHubにプッシュする。チームメイトがプルする。イシューデータのマージコンフリクトはコードと同じように解決される。しかしこれはオプトインであり、必須ではない。

代替と比較する。Jiraにはサーバー(またはAtlassian Cloud)が必要。Linearにはアカウントとインターネット接続が必要。GitHub IssuesにはGitHubのサーバー上のリポジトリが必要。GiteaのようなセルフホストオプションでもWebサービスの実行が必要。

beadsにはディレクトリが必要。Beadboxにはそのディレクトリとダブルクリックが必要。

対象ユーザー

共有ワークキューを通じてコーディネートするAIエージェントを実行し、人間がその作業を視覚的にモニタリングしてステアリングしたいなら、このスタックはあなたのワークフロー向けに構築された。

ソロでプロジェクトを管理し、クラウドアカウントなしでコードの横に住むバージョン管理されたイシュートラッキングが欲しいなら、このスタックはそれにも機能する。

Jiraのエンタープライズ権限モデルや、分散チーム全体でのLinearのコラボレーティブなリアルタイム編集が必要なら、これは適切なツールではない。beadsは設計上ローカルファーストだ。それはトレードオフであり、見落としではない。

はじめよう

beads CLIをgithub.com/steveyegge/beadsからインストールし、Beadboxをインストール:

brew tap beadbox/cask && brew install --cask beadbox

任意のプロジェクトでbeadsデータベースを初期化:

cd your-project
bd init

Beadboxを開き、ディレクトリを指定すれば、イシューボードが表示される。サインアップなし。設定ウィザードなし。「GitHubアカウントを接続」モーダルなし。

Beadboxはベータ期間中無料。