bd-explore

Stelle einem beads-Store Fragen, so wie codegraph explore eine Codebasis abfragt: Ein Aufruf gibt die relevantesten Perlen wortwörtlich zurück – Beschreibung, Notizen, Kommentare, Schließungsgrund – plus die Beziehungsnachbarschaft jedes Treffers, unter einem Ausgabebudget.

Schließt die Lücke, die die Standard-bd-CLI hinterlässt: bd search deckt Titel ab, bd query ist nur strukturiert, und nichts durchsucht Notizen, Kommentare oder Schließungsgründe – genau dort, wo ein ausgereifter Store den Großteil seines Wissens aufbewahrt. bd memories wird ebenfalls indiziert (die einfache CLI kürzt Speicherkörper; dies gibt sie vollständig zurück).

Docs site: 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

Hauptfunktionen

• Tiefe wörtliche Suche: Vollständige Porter-stemmed FTS5-Suche über Titel, Beschreibung, Design, Akzeptanzkriterien, Notizen, datierte Autorenkommentare, Schließungsgründe und Speicher.

• Relationale Nachbarschaftsgraphen: Zeigt 1-Hop-Abhängigkeiten (blocks, blocked-by, parent-child, supersedes, discovered-from, related), Querverweise in Prosa und GitHub-Issue/PR-Links (#NNN).

• Transitiver Explosionsradius: Abfrage transitiver Abhängigkeitsketten (--blast <id>), um Blocker, nachgelagerte Abhängige und Epic-Hierarchie zu sehen, bevor Code berührt wird.

• Eingebauter Stdio-MCP-Server: Null-Abhängigkeits-JSON-RPC-2.0-stdio-Model-Context-Protocol-(MCP)-Server, der das bd_explore-Tool für moderne KI-Codierungsassistenten bereitstellt.

• Multi-Target-Plattform-Installer: Automatische Erkennung und Einrichtung für Claude Code, Gemini CLI, Antigravity IDE, OpenAI Codex, Cursor und AGENTS.md.

• Beads Persistent Memory Injection: Setzt automatisch beads memory (bd remember --key bd-explore), sodass jede bd prime-Sitzung Agenten mit bd-explore-Kontext vorbereitet.

• Strenges Ausgabebudget: Ausgabezeichenbudget (--budget 24000) verhindert Kontextfenster-Überlauf in LLM-Workflows.

• Null Laufzeitabhängigkeiten: Reine Python 3.10+ Standardbibliothek (sqlite3, json, argparse).

Related MCP server: Veridge MCP Server

Installation

Eigenständiger Shell-Installer

Installiert bd-explore in ~/.local/bin und konfiguriert automatisch erkannte Agentenplattformen:

# From repository clone
./install.sh

# Standalone uninstall
./install.sh --uninstall

Python-Paketinstallation

# Standard pip install
pip install .

# Editable install for development
pip install -e .

Verwendung

CLI-Suche

# 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"

Unterstützte Filter

Nicht-Filter-Token (z.B. foo:bar) fallen automatisch in die Freitextsuche. Tipp: Setzen Sie Ihre Suchzeichenfolge in Anführungszeichen, wenn sie Leerzeichen, Filter-Doppelpunkte oder Wörter enthält, die mit Unterbefehlen übereinstimmen (z.B. bd-explore "serve refactor").

Transitiver Explosionsradius

Berechnet den vollständigen transitiven Abhängigkeitsgraphen für jede Perle:

bd-explore --blast 9o32

Ausgaben:

• Upstream-Blocker: Alle Probleme, die diese Perle direkt oder transitiv blockieren.

• Downstream-Blockiert: Alle Probleme, die direkt oder transitiv auf diese Perle warten.

• Epic-Abstammung: Direkte und übergeordnete Epics.

Stdio MCP Server

bd-explore enthält einen eingebauten JSON-RPC-2.0-stdio-MCP-Server für die Agentenintegration. Er unterstützt sowohl zeilengetrenntes JSON (NDJSON) als auch HTTP-artiges Content-Length:-Header-Framing.

Server direkt ausführen:

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

MCP Tool: bd_explore

Stellt das bd_explore-Tool mit Schema bereit:

• query (string): Suchabfragezeichenfolge mit optionalen Feldfiltern (status:open type:task).

• blast (string): Perlen-ID zur Berechnung des transitiven Explosionsradius.

• limit (integer, Standard 5): Maximale Anzahl von Startperlen.

• budget (integer, Standard 24000): Obergrenze des Ausgabezeichenbudgets.

• store (string, optional): Expliziter Store-Pfad oder Repository-Verzeichnis.

Multi-Target-Agent-Installer

bd-explore install erkennt installierte KI-Entwicklertools, fügt MCP-Konfiguration hinzu, injiziert markierungsbegrenzte Agentenrichtlinien und injiziert persistenten Perlen-Speicher.

# 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

Unterstützte Plattformen

Markierungsbegrenzte Anweisungen

Anweisungen werden sicher mit Markierungsbegrenzungen injiziert für saubere Updates und Deinstallationen:

<!-- 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 -->

Was indiziert wird

Designprinzipien

1. Abgeleitet und wegwerfbar. Liest .beads/issues.jsonl (erfordert export.auto: true) in einen SQLite-FTS5-Index unter ~/.cache/bd-explore/, der automatisch neu aufgebaut wird, wenn sich der Export ändert. Der Perlen-Store bleibt die alleinige Quelle der Wahrheit; löschen Sie den Cache frei.

2. Veralterung ist erstklassig. Jeder Treffer wird mit [STATUS · P<n> · type · updated YYYY-MM-DD] gestempelt.

3. Geschlossene Perlen standardmäßig enthalten. Geschichte ist der größte Wert; geschlossene Treffer rangieren bei gleicher Relevanz unter offenen. Verwenden Sie status:open, um einzugrenzen.

4. Kontextfensterfreundlich. Setzt Ausgabezeichenbudgets strikt durch, um bequem in Agentengespräche zu passen.

Architektur

Die Explore-Pipeline sitzt hinter einem tiefen Modul; alles andere passt sich daran an.

              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 — die einzige Schnittstelle, die Aufrufer benötigen: explore() / blast() rein, formatierter Text raus, ExploreError bei Fehler.

• index.py — parst .beads/issues.jsonl und bd memories in einen abgeleiteten SQLite-FTS5-Cache, der atomar neu aufgebaut wird, wenn sich der Export ändert.

• search.py — BM25-Suche und Abfrageparsing; hydrate() holt batchweise Nachbarschaften und Titel (insgesamt zwei Abfragen), render() ist rein und besitzt die gesamte Budget-/Kürzungslogik.

• installer/ — Multi-Target-Plattformadapter hinter einer gemeinsamen Installations-/Deinstallationsnaht.

Domänenvokabular befindet sich in CONTEXT.md; Repo-Konventionen in CLAUDE.md.

Entwicklung

# 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 führt die Suite auf Linux und macOS über Python 3.10–3.14 aus. Siehe CHANGELOG.md für die Versionsgeschichte.

Anforderungen

• Python 3.10+

• SQLite mit FTS5-Virtual-Table-Unterstützung (Standard in offiziellen CPython-Distributionen)

Lizenz

MIT-Lizenz. Siehe LICENSE für Details.