Skip to main content
Glama
deenesjakoruzh
halaprix

bd-explore

by halaprix
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

bd-explore

CI Python 3.10+ Zero dependencies License: MIT

beadsストアに質問する、codegraph exploreがコードベースに質問するのと同じ方法で: 1回の呼び出しで最も関連性の高いbeadsをそのまま（説明、メモ、コメント、クローズ理由）返し、さらに各ヒットの関係性の近傍を、出力予算の範囲内で返します。

標準のbd CLIに残されたギャップを埋めます: bd searchはタイトルを検索し、bd queryは構造化データのみを検索し、メモ、コメント、クローズ理由は検索しません。成熟したストアでは、これらの領域にほとんどのナレッジが保存されています。bd memoriesもインデックス化されます（通常のCLIはメモリ本体を切り詰めますが、これは全文を返します）。

ドキュメントサイト: https://halaprix.github.io/bd-explore/

$ bd-explore "why did we re-point SYRP status:open"

═══ SYRP-142 [OPEN · P1 · task · updated 2026-08-12]
    Re-point SYRP feed to the v2 oracle
    The v1 oracle staleness window regressed after the chain upgrade…
    COMMENT (ksz 2026-08-11):
    Decision: re-point rather than patch v1 — see close reason on SYRP-118.
    ── neighborhood ──
    blocked by: SYRP-139 — Oracle failover runbook [in_progress]
    child of: SYRP-100 — Oracle migration epic [in_progress]
    mentions: SYRP-118

主な機能

  • 完全な逐語検索: タイトル、説明、設計、受け入れ基準、メモ、日付付き著者コメント、クローズ理由、メモリに対して、完全なPorterステミングベースのFTS5検索を実行。

  • 関係性近傍グラフ: 1ホップの依存関係（blocks、blocked-by、parent-child、supersedes、discovered-from、related）、クロスプローズのメンション参照、GitHub Issue/PRリンク（#NNN）を表示。

  • 推移的ブラスト半径: 推移的依存チェーンをクエリ（--blast <id>）し、コードに触れる前にブロッカー、下流の依存先、エピック階層を確認。

  • 内蔵Stdio MCPサーバー: ゼロ依存のJSON-RPC 2.0 stdio Model Context Protocol（MCP）サーバーを搭載し、bd_exploreツールを最新のAIコーディングアシスタントに提供。

  • マルチターゲットプラットフォームインストーラー: Claude Code、Gemini CLI、Antigravity IDE、OpenAI Codex、Cursor、AGENTS.mdの自動検出とセットアップ。

  • Beads永続メモリ注入: beadsメモリ（bd remember --key bd-explore）を自動設定し、bd primeセッションごとにエージェントにbd-exploreコンテキストを付与。

  • 厳格な出力予算管理: 出力文字予算（--budget 24000）により、LLMワークフローでのコンテキストウィンドウ肥大化を防止。

  • ランタイム依存ゼロ: 純粋なPython 3.10+標準ライブラリ（sqlite3、json、argparse）。

Related MCP server: recall

インストール

スタンドアロンシェルインストーラー

bd-exploreを~/.local/binにインストールし、検出されたエージェントプラットフォームを自動設定:

# From repository clone
./install.sh

# Standalone uninstall
./install.sh --uninstall

Pythonパッケージインストール

# Standard pip install
pip install .

# Editable install for development
pip install -e .

使い方

CLI検索

# Free text search across all fields (porter-stemmed FTS)
bd-explore "why did we re-point SYRP"

# Compose field filters with free text (codegraph-style)
bd-explore "hash refresh status:open type:task priority:1"
bd-explore "swap oracle epic:rpm5"

# Target specific store or force reindex
bd-explore --store ~/Projects/my-project "auth refactor"
bd-explore --rebuild

# Control limits and output budget
bd-explore -n 3 --budget 16000 "database migration"

対応フィルター

フィルター

構文 / 値

説明

status:

open, in_progress, closed, deferred, all

ステータスでフィルター（allはクローズ済みビーズも低ランクで検索）

type:

bug, feature, task, epic, chore

課題タイプでフィルター

priority:

0, 1, 2, 3, 4 (または P0..P4)

優先度レベルでフィルター

epic:

<IDまたはサフィックス>

特定のエピックに属する課題をフィルター

id:

<IDまたは部分文字列>

IDで課題をマッチ（部分文字列 / 前方一致）

フィルター以外のトークン（例: foo:bar）は自動的に全文検索にフォールスルーします。 ヒント: 検索文字列にスペース、フィルターのコロン、またはサブコマンドと一致する単語が含まれる場合は引用符で囲んでください（例: bd-explore "serve refactor"）。

推移的ブラスト半径

任意のビーズの完全な推移的依存関係グラフを計算:

bd-explore --blast 9o32

出力:

  • 上流ブロッカー: このビーズを直接的または推移的にブロックしているすべての課題。

  • 下流ブロック対象: このビーズを直接的または推移的に待機しているすべての課題。

  • エピック祖先: 直接および祖先のエピック。

Stdio MCPサーバー

bd-exploreにはエージェント統合用の内蔵JSON-RPC 2.0 stdio MCPサーバーが含まれています。改行区切りJSON（NDJSON）とHTTP形式のContent-Length:ヘッダーフレーミングの両方をサポートします。

サーバーを直接実行:

bd-explore serve --mcp
# Or with explicit store:
bd-explore serve --mcp --store ~/Projects/my-project

MCPツール: bd_explore

スキーマ付きのbd_exploreツールを公開:

  • query (文字列): オプションのフィールドフィルター（status:open type:task）付き検索クエリ文字列。

  • blast (文字列): 推移的ブラスト半径を計算するビーズID。

  • limit (整数, デフォルト5): シードビーズの最大数。

  • budget (整数, デフォルト24000): 出力文字予算の上限。

  • store (文字列, オプション): 明示的なストアパスまたはリポジトリディレクトリ。

マルチターゲットエージェントインストーラー

bd-explore installはインストール済みのAI開発ツールを検出し、MCP設定を追加し、マーカーフェンスで囲まれたエージェントガイドラインを注入し、beads永続メモリを注入します。

# Interactive setup (prompts for targets and location)
bd-explore install

# Automated non-interactive batch install
bd-explore install --yes

# Install for specific targets and location
bd-explore install --targets claude,gemini,cursor --location global --auto-allow --yes

# Uninstall configurations
bd-explore uninstall --yes

# Print MCP configuration snippet without modifying files
bd-explore print-config claude
bd-explore print-config cursor

対応プラットフォーム

プラットフォーム

MCP設定

指示とルール

Claude Code

~/.claude.json / .mcp.json

~/.claude/CLAUDE.md / CLAUDE.md

Gemini CLI / Antigravity CLI

~/.gemini/settings.json / .gemini/settings.json

~/.gemini/GEMINI.md / GEMINI.md

Antigravity IDE

~/.gemini/config/mcp_config.json

IDE指示 / ワークスペースルール

OpenAI Codex

~/.codex/config.toml

~/.codex/AGENTS.md

Cursor

~/.cursor/mcp.json / .cursor/mcp.json

.cursor/rules/bd-explore.mdc

汎用エージェントルール

—

~/.config/AGENTS.md / AGENTS.md

マーカーフェンスで囲まれた指示

指示はマーカーフェンスで安全に注入され、クリーンな更新とアンインストールが可能:

<!-- BD_EXPLORE_START -->
## bd-explore

In repositories with a beads store (a `.beads/` directory exists at the repo root), reach for `bd-explore` BEFORE searching raw files or relying only on `bd search`:

- **MCP tool** (when available): `bd_explore` answers questions about beads/issues/decisions/memories verbatim — description, notes, comments, close reason, plus relationship neighborhood under an output budget.
- **Shell** (always works): `bd-explore "<query>"` (e.g. `bd-explore "why did we re-point SYRP status:open"`, `bd-explore --blast <id>`).

If there is no `.beads/` directory, skip bd-explore.
<!-- BD_EXPLORE_END -->

インデックス化されるもの

コンテンツ

ソース

備考

タイトル、説明、設計、受け入れ基準

.beads/issues.jsonl

プライマリ課題コンテンツ

メモ、クローズ理由

.beads/issues.jsonl

重要なコンテキストと事後分析

著者コメント

.beads/issues.jsonl

タイムスタンプ付き会話履歴

メモリ本体全文

bd memories --json

永続メモリレコード

明示的な依存関係エッジ

dependencies 配列

blocks、parent-child、supersedes、related など

メンションエッジ

プロズ内相互参照

課題プロズ全体で引用されたビーズIDの正規表現マッチをマイニング

GitHub参照

プロズ内相互参照

#NNN Issueおよびプルリクエスト参照をマイニング

設計原則

  1. 派生可能で使い捨て可能。 .beads/issues.jsonl（export.auto: trueが必要）を読み取り、~/.cache/bd-explore/にSQLite FTS5インデックスを作成。エクスポートが変更されると自動的に再構築。beadsストアが唯一の情報源であり、キャッシュは自由に削除可能。

  2. 陳腐性は第一級の概念。 すべてのヒットに[ステータス · P<n> · タイプ · 更新日 YYYY-MM-DD]のスタンプが付けられます。

  3. クローズ済みビーズもデフォルトで含める。 履歴が価値の大部分を占めます。クローズ済みヒットは、同等の関連性でオープンより低くランク付けされます。絞り込むにはstatus:openを使用。

  4. コンテキストウィンドウに優しい。 出力文字予算を厳格に強制し、エージェント会話に快適に収まるようにします。

アーキテクチャ

exploreパイプラインは1つの深いモジュールの背後にあり、他のすべてはそれに適応します。

              CLI (cli.py)              MCP server (mcp.py)
                   │  thin adapters: args / JSON-RPC  │
                   └──────────────┬───────────────────┘
                                  ▼
                      Explorer (explorer.py)
        explore(query, …) → str   ·   blast(id, …) → str
     owns store discovery, index freshness, connection
       lifetime, defaults/clamping, canonical errors
                   ┌──────────────┴───────────────────┐
                   ▼                                  ▼
          index.py (SQLite FTS5,             search.py (BM25 search,
          mention mining, cache)             hydrate → pure render)

  • explorer.py — 呼び出し元が唯一必要とするインターフェース: explore() / blast()を入力し、整形テキストを出力、失敗時はExploreErrorを返す。

  • index.py — .beads/issues.jsonlとbd memoriesを解析し、派生SQLite FTS5キャッシュに格納。エクスポートが変更されるとアトミックに再構築。

  • search.py — BM25検索とクエリ解析。hydrate()は近傍とタイトルをバッチフェッチ（合計2クエリ）、render()は純粋関数で予算と切り詰めロジックをすべて所有。

  • installer/ — 共通のインストール/アンインストールシームの背後にあるマルチターゲットプラットフォームアダプタ。

ドメイン語彙はCONTEXT.mdに、リポジトリ規約はCLAUDE.mdにあります。

開発

# Run the full test suite (stdlib unittest — no test dependencies either)
PYTHONPATH=src python3 -m unittest discover tests -v

# Run one module / one case
PYTHONPATH=src python3 -m unittest tests.test_explorer
PYTHONPATH=src python3 -m unittest tests.test_render.TestRenderPure

# Editable install
pip install -e .

CIはLinuxとmacOS上でPython 3.10～3.14のスイートを実行します。リリース履歴はCHANGELOG.mdを参照してください。

要件

  • Python 3.10+

  • FTS5仮想テーブルをサポートするSQLite（公式CPythonディストリビューションに標準搭載）

ライセンス

MITライセンス。詳細はLICENSEを参照してください。

This server cannot be deployed

Pay for results, not tokens.Fund a bounty. Let AI agents compete and collaborate to solve your problems.agentbounties.appAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • EzRAG MCP Server

    benbjurstrom
    A
    license
    Not graded
    quality
    D
    maintenance
    Provides semantic search and keyword search over Obsidian notes, along with direct note retrieval, allowing external AI agents to query and access the vault.
    19
    BSD Zero Clause

  • recall

    tools-for-agents
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables agents to query across all their memory stores (brain, team, reading, code) in one call, returning a token-budgeted, ranked briefing with results interleaved from each source.
    14 npm
    MIT

  • bd-graph MCP Server

    halaprix
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables coding agents to query a temporal knowledge graph derived from a beads issue tracker via read-only Cypher queries, exposing current rules, supersession chains, and provenance without LLM API keys.
    MIT

  • Codex Jev

    Hyper-AI-Lab
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables coding agents to discover, optionally rank, and exactly read bounded source-addressed evidence from large repositories and noisy logs, with local-only privacy controls and quota-aware recovery.
    1
    MIT