bd-explore

Pregunta a un almacén de beads preguntas, de la misma manera que codegraph explore pregunta a un código base: una llamada devuelve las beads más relevantes textualmente — descripción, notas, comentarios, motivo de cierre — además del vecindario de relaciones de cada acierto, bajo un presupuesto de salida.

Llena el vacío que deja la CLI estándar bd: bd search cubre títulos, bd query es solo estructurado, y nada busca notas, comentarios o motivos de cierre — que es donde un almacén maduro guarda la mayor parte de su conocimiento. bd memories también está indexado (la CLI simple trunca los cuerpos de memoria; esto los devuelve completos).

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

Características principales

• Búsqueda textual profunda: Búsqueda FTS5 completa con derivación de Porter en título, descripción, diseño, criterios de aceptación, notas, comentarios de autor con fecha, motivos de cierre y memorias.

• Grafos de vecindario relacional: Expone dependencias de 1 salto (blocks, blocked-by, parent-child, supersedes, discovered-from, related), referencias de menciones entre textos, y enlaces a issues/PR de GitHub (#NNN).

• Radio de explosión transitivo: Consulta cadenas de dependencias transitivas (--blast <id>) para ver bloqueadores, dependientes aguas abajo y jerarquía de épicas antes de tocar código.

• Servidor MCP Stdio integrado: Servidor JSON-RPC 2.0 stdio del Protocolo de Contexto de Modelo (MCP) sin dependencias que proporciona la herramienta bd_explore a asistentes de codificación de IA modernos.

• Instalador multiplataforma: Descubrimiento y configuración automatizados para Claude Code, Gemini CLI, Antigravity IDE, OpenAI Codex, Cursor y AGENTS.md.

• Inyección de memoria persistente de beads: Establece automáticamente la memoria de beads (bd remember --key bd-explore) para que cada sesión de bd prime prepare a los agentes con el contexto de bd-explore.

• Presupuesto de salida estricto: El presupuesto de caracteres de salida (--budget 24000) evita el desbordamiento de la ventana de contexto en flujos de trabajo con LLM.

• Cero dependencias en tiempo de ejecución: Biblioteca estándar de Python 3.10+ pura (sqlite3, json, argparse).

Related MCP server: Veridge MCP Server

Instalación

Instalador de shell independiente

Instala bd-explore en ~/.local/bin y configura automáticamente las plataformas de agente detectadas:

# From repository clone
./install.sh

# Standalone uninstall
./install.sh --uninstall

Instalación del paquete Python

# Standard pip install
pip install .

# Editable install for development
pip install -e .

Uso

Búsqueda 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"

Filtros admitidos

Los tokens que no son filtros (p. ej. foo:bar) pasan automáticamente a la búsqueda de texto libre. Consejo: Pon entre comillas tu cadena de búsqueda cuando contenga espacios, dos puntos de filtro o palabras que coincidan con subcomandos (p. ej. bd-explore "serve refactor").

Radio de explosión transitivo

Calcula el grafo de dependencias transitivas completo para cualquier bead:

bd-explore --blast 9o32

Salidas:

• Bloqueadores ascendentes: Todos los issues que bloquean directa o transitivamente esta bead.

• Bloqueados descendentes: Todos los issues que esperan directa o transitivamente esta bead.

• Ascendencia de épica: Épicas directas y antecesoras.

Servidor MCP Stdio

bd-explore incluye un servidor MCP stdio JSON-RPC 2.0 integrado para la integración con agentes. Soporta tanto JSON delimitado por nuevas líneas (NDJSON) como el encabezado Content-Length: al estilo HTTP.

Ejecuta el servidor directamente:

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

Herramienta MCP: bd_explore

Expone la herramienta bd_explore con el esquema:

• query (string): Cadena de consulta de búsqueda con filtros de campo opcionales (status:open type:task).

• blast (string): ID de bead para calcular el radio de explosión transitivo.

• limit (integer, default 5): Número máximo de beads semilla.

• budget (integer, default 24000): Límite del presupuesto de caracteres de salida.

• store (string, optional): Ruta explícita del almacén o directorio del repositorio.

Instalador de agente multiplataforma

bd-explore install descubre las herramientas de desarrollo de IA instaladas, añade configuración MCP, inyecta directrices de agente delimitadas por marcadores e inyecta memoria persistente de 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

Plataformas admitidas

Instrucciones delimitadas por marcadores

Las instrucciones se inyectan de forma segura con delimitadores de marcadores para actualizaciones y desinstalaciones limpias:

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

Qué se indexa

Principios de diseño

1. Derivado y desechable. Lee .beads/issues.jsonl (requiere export.auto: true) en un índice SQLite FTS5 bajo ~/.cache/bd-explore/, reconstruido automáticamente cuando la exportación cambia. El almacén de beads sigue siendo la única fuente de verdad; elimina la caché libremente.

2. La obsolescencia es de primera clase. Cada acierto lleva la marca [STATUS · P<n> · type · updated YYYY-MM-DD].

3. Beads cerradas incluidas por defecto. La historia es la mayor parte del valor; los aciertos cerrados se clasifican por debajo de los abiertos con igual relevancia. Usa status:open para reducir.

4. Amigable con la ventana de contexto. Aplica estrictamente presupuestos de caracteres de salida para que encajen cómodamente en conversaciones de agentes.

Arquitectura

El pipeline de exploración se encuentra detrás de un módulo profundo; todo lo demás se adapta a él.

              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 — la única interfaz que necesitan los llamadores: explore() / blast() de entrada, texto formateado de salida, ExploreError en caso de error.

• index.py — analiza .beads/issues.jsonl y bd memories en una caché SQLite FTS5 derivada, reconstruida atómicamente cuando la exportación cambia.

• search.py — búsqueda BM25 y análisis de consultas; hydrate() obtiene por lotes vecindarios y títulos (dos consultas en total), render() es pura y posee toda la lógica de presupuesto/truncamiento.

• installer/ — adaptadores de plataforma multiobjetivo detrás de una costura común de instalación/desinstalación.

El vocabulario del dominio se encuentra en CONTEXT.md; las convenciones del repositorio en CLAUDE.md.

Desarrollo

# 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 ejecuta la suite en Linux y macOS con Python 3.10–3.14. Consulta CHANGELOG.md para el historial de versiones.

Requisitos

• Python 3.10+

• SQLite con soporte de tabla virtual FTS5 (estándar en distribuciones oficiales de CPython)

Licencia

Licencia MIT. Consulta LICENSE para más detalles.