bd-explore

Задавайте вопросы хранилищу beads так же, как codegraph explore задает вопросы кодовой базе: один вызов возвращает наиболее релевантные beads дословно — описание, заметки, комментарии, причину закрытия — плюс окрестности связей каждого совпадения, в рамках бюджета вывода.

Заполняет пробел, оставленный стандартным CLI bd: 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

Ключевые особенности

• Глубокий дословный поиск: Полнотекстовый поиск FTS5 со стеммингом Портера по заголовку, описанию, дизайну, критериям приемки, заметкам, датированным комментариям авторов, причинам закрытия и памяти.

• Графы реляционных окрестностей: Отображает зависимости первого уровня (blocks, blocked-by, parent-child, supersedes, discovered-from, related), перекрестные ссылки на упоминания в тексте и ссылки на задачи/PR GitHub (#NNN).

• Транзитивный радиус поражения: Запрос транзитивных цепочек зависимостей (--blast <id>) для просмотра блокирующих, нижестоящих зависимостей и иерархии эпиков до касания кода.

• Встроенный Stdio MCP сервер: Сервер Model Context Protocol (MCP) stdio JSON-RPC 2.0 с нулевыми зависимостями, предоставляющий инструмент 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"

Поддерживаемые фильтры

Токены, не являющиеся фильтрами (например, foo:bar), автоматически переходят в полнотекстовый поиск. Совет: Заключайте строку поиска в кавычки, если она содержит пробелы, двоеточия фильтров или слова, совпадающие с подкомандами (например, bd-explore "serve refactor").

Транзитивный радиус поражения

Вычислить полный транзитивный граф зависимостей для любого bead:

bd-explore --blast 9o32

Вывод:

• Вышестоящие блокирующие: Все задачи, прямо или транзитивно блокирующие этот bead.

• Нижестоящие заблокированные: Все задачи, прямо или транзитивно ожидающие этот bead.

• Родословная эпиков: Прямые и родительские эпики.

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 (string): Строка поискового запроса с необязательными фильтрами полей (status:open type:task).

• blast (string): ID bead для вычисления транзитивного радиуса поражения.

• limit (integer, по умолчанию 5): Максимальное количество начальных beads.

• budget (integer, по умолчанию 24000): Предел бюджета символов вывода.

• store (string, необязательный): Явный путь к хранилищу или каталог репозитория.

Многоцелевой установщик агентов

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

Поддерживаемые платформы

Инструкции, ограниченные маркерами

Инструкции безопасно внедряются с маркерными ограничителями для чистого обновления и удаления:

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

Что индексируется

Принципы дизайна

1. Производный и одноразовый. Читает .beads/issues.jsonl (требуется export.auto: true) в индекс SQLite FTS5 в ~/.cache/bd-explore/, автоматически перестраивается при изменении экспорта. Хранилище beads остается единственным источником истины; удаляйте кеш свободно.

2. Устаревание — первостепенно. Каждое совпадение помечается [STATUS · P<n> · type · updated YYYY-MM-DD].

3. Закрытые beads включены по умолчанию. История составляет большую часть ценности; закрытые совпадения ранжируются ниже открытых при равной релевантности. Используйте status:open для сужения.

4. Дружелюбен к контекстному окну. Строго соблюдает бюджеты символов вывода, чтобы комфортно вписываться в разговоры агентов.

Архитектура

Конвейер explore находится за одним глубоким модулем; все остальное адаптируется к нему.

              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() пакетно извлекает окрестности и заголовки (всего два запроса), 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+

• SQLite с поддержкой виртуальной таблицы FTS5 (стандартно в официальных дистрибутивах CPython)

Лицензия

Лицензия MIT. Подробности см. в LICENSE.