bd-explore

bd-explore
ask your issue store questions.

One query returns the most relevant beads verbatim — description, notes, comments, close reason — plus each hit's relationship neighborhood, under a strict output budget.

A zero-dependency CLI and MCP server for beads stores. Pure Python 3.10+ standard library: nothing to install but the tool itself.

$ install source on GitHub
epic · in_progress open blocked closed
session — a question, answered verbatim
$ 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; consumers saw 40s-stale prices under load.    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 … [output capped at 24000 chars; 2 additional hit(s) omitted. Use 'bd show <id>' or higher --budget]
filters compose with free text
$ bd-explore "hash refresh status:open type:task priority:1"
$ bd-explore "swap oracle epic:rpm5"
$ bd-explore -n 3 --budget 16000 "database migration"
status:open · in_progress · closed · deferred · all
type:bug · feature · task · epic · chore
priority:0–4, or P0–P4
epic:beads belonging to an epic, by id or suffix
id:match bead ids by substring
blast radius — transitive closure of one bead
$ bd-explore --blast SYRP-139

═══ SYRP-139 [IN_PROGRESS · P1 · task · updated 2026-08-14]
    Oracle failover runbook

this bead is blocked by (transitively): 1
  SYRP-131  Alerting for feed staleness [open]

beads this blocks (transitively): 3
  SYRP-142  Re-point SYRP feed to the v2 oracle [open]
  SYRP-150  Decommission v1 oracle [open]
  SYRP-151  Close out migration epic [deferred]

epic ancestry: 1
  SYRP-100  Oracle migration epic [in_progress]
one command wires up your agents
$ bd-explore install --targets claude,cursor --yes

Installation results:
  ✓ claude: configured (global) -> ~/.claude.json, ~/.claude/CLAUDE.md
  ✓ cursor: configured (global) -> ~/.cursor/mcp.json
  ✓ beads memory: injected

$ bd-explore print-config claude
{
  "mcpServers": {
    "bd-explore": { "command": "bd-explore", "args": ["serve"] }
  }
}
Claude CodeGemini CLIAntigravityCodexCursorAGENTS.md

Two commands to first answer.

Requires Python 3.10+ with SQLite FTS5 (standard in CPython) and a repo with a .beads/ store.

install
# install from source
$ pip install git+https://github.com/halaprix/bd-explore

# or: clone and use the shell installer (~/.local/bin + agent setup)
$ git clone https://github.com/halaprix/bd-explore && cd bd-explore && ./install.sh

# first question
$ bd-explore "what do we know about auth refactor"