Repository navigation
Releases
brigid 2.1.0
Minor release adding cache management subcommands and hit/miss tracking,
following the 2.0.0 breaking release that adopted llm-kernel and removed
brigid-llm.
Cache management (issue #300)
- Added
brigid cache prunesubcommand: clears all cache entries and
removes the SQLite database file and its WAL/SHM sidecars. Uses a
two-phase approach for safety under concurrency: (1)DELETE FROM kv
inside aBEGIN IMMEDIATEtransaction, thenCOMMIT; (2)
PRAGMA wal_checkpoint(TRUNCATE)after commit to flush the WAL into
the main DB; (3) file removal after checkpoint. If a concurrent
process reopens the database between phases, it finds an empty cache
(0 entries) — not a corrupted one. Replaces the previous manual
rm -rfworkaround. - Added
brigid cache statssubcommand: prints the cache file path, entry
count, and on-disk size (including WAL/SHM sidecars). Opens the database
read-only so it never creates or modifies cache files. - Added
brigid_pipeline::CountingKvStore: aKvStorewrapper that
counts cache hit/miss statistics at the store level. WhenCacheClient
callsstore.get(key), theCountingKvStorecountsSomeas a hit and
Noneas a miss. This is the correct layer for cache statistics — no
duplicated cache-key derivation, no race conditions, no extra KV lookups.
ExportsCacheStats,CacheStatsHandle, andCountingKvStorefrom
brigid_pipeline. Wired intobuild_live_clientso the CLI'sgenerate
andgenerate --each-appverbose output reports cache hit/miss counts
and hit rate. - Added
brigid_pipeline::CacheAdmin: admin operations on a
SqliteKvStorecache database (entry_count,on_disk_size,prune).
Encapsulates SQLite-specific details (table name, WAL/SHM sidecars,
locking) so the CLI layer doesn't need a directrusqlitedependency.
Thebrigid cache pruneandbrigid cache statssubcommands delegate to
these methods. - Moved
rusqlitedependency frombrigid-clitobrigid-pipeline.
The CLI is now a thin wiring layer that callsCacheAdminmethods. - Updated
BRIGID_NO_CACHEhelp text to mentionbrigid cache pruneand
brigid cache stats.
Phase 4: brigid-llm removal (issue #297)
- Removed
brigid-llmcrate from the workspace. The CLI now uses
llm_kernel::llm::{OpenAIClient, RetryClient, CacheClient}directly — no
adapter layer. - The
LegacyLlmClientadapter,legacy_llm_errormapping, and
brigid_llm::DiskCachehave been replaced withllm_kernelnative types. - Provider resolution logic moved to
brigid_pipeline::llmas
resolve_llm_configandbuild_live_client. This keeps the CLI a thin
wrapper (per the ARCHITECTURE.md layering rule) and makes the security-
critical provider/key-chain logic unit-testable in the library crate.
15 new tests cover key isolation, blank-env handling, host allowlist
enforcement, and provider inference from base URL. - Retry/backoff:
OpenAIClientis now wrapped inllm_kernel::RetryClient
with the defaultRetryConfig(max 3 retries, 1s base delay, exponential
backoff, Retry-After capped at 5 minutes). This matches the bounded
exponential backoff guarantees of the removedbrigid-llmclient. - Cache backend changed from
brigid_llm::DiskCache(file-based with LRU
eviction and size limits) tollm_kernel::store::SqliteKvStore(SQLite-backed
KV store). Trade-offs:- The SQLite cache does not enforce a size limit. Use
brigid cache prune
to delete all cached responses, or setBRIGID_NO_CACHE=1to disable
caching entirely. - Cache keys include the model name and full request JSON (via
llm_kernel::CacheClient), so switching models or providers does not
produce incorrect cache hits. - Cache hit/miss stats are available via
brigid_pipeline::CountingKvStore, which countsKvStorelookups.
The CLI's verbose output reports cache status; usebrigid cache stats
for entry count and on-disk size. - The cache stores full prompt and response bodies on disk. Crawled
repositories may contain secrets in source files; these are truncated and
batched before being sent to the LLM, but the cache persists the full
prompt+response. This is the same exposure profile as the previous
DiskCache. Users with sensitive repos should disable caching
(BRIGID_NO_CACHE=1) or point the cache at an encrypted volume.
- The SQLite cache does not enforce a size limit. Use
- Removed
async-traitdependency frombrigid-cli(no longer needed without
the adapter).
brigid 1.3.0
Minor release adding two major features: an MCP (Model Context Protocol) server
for AI assistant integration (ADR 0015) and a Graph Provider abstraction for
structural code analysis integration (ADR 0016).
Added
-
MCP server (ADR 0015). New
brigid-mcpcrate exposes brigid's checkpoint
knowledge graph to AI assistants (Claude Desktop, Cursor, Windsurf) via the
Model Context Protocol. The server is read-only and loads a previously
generated checkpoint directory into memory, serving:- Resources —
checkpoint://URIs for metadata, abstractions,
relationships, chapter ordering, file inventory, individual chapters, setup
guide, architecture overview, and a combined tutorial index. - Tools — 7 graph query/lookup tools:
find_abstraction_for_file,
abstraction_dependencies,files_for_abstraction,
relevance_ranked_chapters,chapter_for_file,list_abstractions,
is_checkpoint_stale. - Prompts — 3 onboarding workflows:
onboard_to_codebase,
explain_file,deep_dive_abstraction. - Transport — stdio transport via the
rmcpcrate (v3.1.1), the official
Rust MCP SDK. The server advertises all three capabilities (resources,
tools, prompts) and supports cache hints for MCP 2026-07-28 clients.
- Resources —
-
Graph Provider abstraction (ADR 0016). New
GraphProvidertrait in
brigid-coreallows external structural analysis tools (call graphs, code
knowledge graphs) to enhance brigid's pipeline with structural data. The
NoneProvideris the default — all methods return empty/None, so brigid
works exactly as before (LLM-only) with zero configuration. The graph provider
is an opt-in enhancement integrated into three pipeline stages:- Identify stage — community context in the map prompt, multimodal concept
context in the reduce prompt. - Relationships stage —
structurally_verified: Option<bool>field on
Relationshiprecords whether the graph provider's call graph confirms or
contradicts each LLM-extracted edge. - Order stage — hub concepts from the graph provider inform early chapter
placement for key abstractions.
- Identify stage — community context in the map prompt, multimodal concept
-
GraphProviderConfiginRunConfig— configurable via[graph_provider]
inbrigid.toml,BRIGID_GRAPH_PROVIDERenvironment variable, and CLI.
Supportstype = "none"(default) andtype = "codegraph"with adata_path
pointing to a CodeGraph SQLite database.
Changed
- New
brigid-mcpcrate added to the workspace. Does not affect existing
crates — the MCP server is a separate binary that reads checkpoints produced
bybrigid generate.
brigid 1.2.0
Minor release adding OpenRouter as a first-class LLM provider (ADR 0017) and
wiring RunConfig.provider / RunConfig.model into live client construction
for all presets.
Added
- OpenRouter as a first-class LLM provider (ADR 0017). Set
provider = "openrouter"and an explicit model (e.g.openai/gpt-4o) in
brigid.toml, orBRIGID_PROVIDER/BRIGID_MODEL. Defaults to
https://openrouter.ai/api/v1, allowlistsopenrouter.ai, accepts
OPENROUTER_API_KEY, and sends OpenRouter attribution headers.RunConfig.provider
andRunConfig.modelnow drive live client construction for all presets
(DeepSeek, OpenAI, OpenRouter, custom).
Changed
RunConfig.providerandRunConfig.modelare now operational. These
fields were previously parsed frombrigid.toml/ CLI / env but ignored
during client construction. They now select provider presets (base URL,
API-key env var, host allowlist, attribution headers) for DeepSeek, OpenAI,
OpenRouter, and custom providers. This is a behavior change that enables new
capability rather than a regression; existing env-only configurations
(BRIGID_LLM_BASE_URL,BRIGID_LLM_API_KEY) continue to work unchanged.- OpenAI and OpenRouter now require an explicit model. DeepSeek retains
deepseek-chatas a safe default; OpenAI and OpenRouter have no safe
universal default and will error with a clear message if no model is set.
brigid 1.1.0
Minor release with three new features (blog-post tutorial style, lenient
app validation, incremental chapter regeneration), four bug fixes, and a
Windows CI flake fix.
Added
- Blog-post tutorial style (
--tutorial-style). Tutorials can now be
generated in two styles:blog(new default — shorter, simpler, more
conversational) andbook(the previous long-form style). The flag
selects the chapter outline and architecture overview templates. The
TutorialStyleenum is threaded throughRunConfig,GenerateConfig,
ChaptersConfig, andOverviewInput(#267, #270). --strict-app-validationflag. When set, the overview stage fails on
unknown app paths in LLM output. By default (changed from previous
behavior), unknown apps now produce a warning instead of an error,
letting generation proceed with the valid apps (#265, #269).- Incremental chapter regeneration. When
--sinceis set, only
chapters whose abstractions touch changed files are re-generated.
Chapters for unchanged abstractions are reused from the checkpoint,
saving LLM calls and time on incremental runs. Uses aHashSetfor
O(1) path lookups with cross-platform normalization (#272).
Changed
- Default tutorial style is now
blog. Users who want the previous
long-form output should pass--tutorial-style book. The blog style
produces shorter chapters with fewer diagrams, optimized for quick
onboarding rather than comprehensive reference. - Overview app validation is lenient by default. Previously, unknown
app paths in the architecture overview caused a hard error. Now they
produce a warning and generation continues. Pass--strict-app-validation
to restore the old behavior.
Fixed
- Checkpoint collision when
--dirdiffers. Thesource_dirfield is
now included in the checkpoint'sconfig_hashidentity check, preventing
silent checkpoint reuse when the same output directory is used for
different source directories (#266, #268). - Unclosed LLM code fences. The YAML/JSON extraction layer now
tolerates unclosed```fences in LLM output and sends
max_tokensto prevent truncation (#262, #263). - Relationship endpoint range-checking. Follow-up tests for PR #259:
relationship endpoint tests, mock fallback warning, andFORCE_MOCK
documentation (#260, #261). - Windows CI flake in cache tests.
temp_root()now creates the
temp directory synchronously, eliminating a race on Windows CI runners
where 8.3 short names causedNotFounderrors (#271).
brigid 1.0.2
Patch release that hardens the CLI's LLM-client selection and the
relationships stage, adds a security policy, and closes a codecov patch
coverage gap.
Changed
- CLI now fails closed on missing API credentials.
build_real_llm_client
returnsResultinstead ofOption; when noBRIGID_LLM_API_KEY/
DEEPSEEK_API_KEYis set andBRIGID_FORCE_MOCKis not enabled, the CLI
exits with a clear LLM-configuration error instead of silently emitting
placeholder mock output. Anyone who relied on the silent mock fallback
must now setBRIGID_FORCE_MOCK=1explicitly. BRIGID_FORCE_MOCKrecognizes falsy values.0,false,no,off
(case-insensitive) and empty/whitespace now disable forced mock output;
any other non-blank value enables it.None(env var unset) is disabled.
Added
SECURITY.mdpolicy with supported-versions statement and private
vulnerability reporting instructions via GitHub Security Advisories.- Relationship endpoint range-checking. The relationships stage now
validates thatfrom_abstraction/to_abstractionindices fall within
the identify result, returningRelationshipsError::EndpointOutOfRange
instead of panicking on malformed LLM output. - Centralized mock placeholder responses. The
PLACEHOLDER_*constants
andmock_clienthelper are now shared acrosscmd_identify,
cmd_generate, andcmd_generate_each_app, removing three-way
duplication. - Mock fault-injection unit tests.
mock_fail_error()is extracted as a
pure function and unit-tested for all 5 fault keywords (timeout,
ratelimit,provider,parse,network/unknown). - Integration tests for the non-
--single-shotmock path,
--each-app --review-chapters, and--each-app --force-setupbranches.
Fixed
- Codecov patch coverage on PR #259: 84.61% → 89.11% (target: 85%).
brigid 1.0.1
Patch release to add per-crate README files and make the crates.io pages
self-documenting.
Added
- README.md for each workspace crate (
brigid-core,brigid-crawl,brigid-llm,brigid-pipeline,brigid-cli) with badges, descriptions, usage examples, and links back to the mainbrigidrepository. readme = "README.md"entry in each crateCargo.tomlso crates.io renders the README.
Fixed
- Replaced the unsupported crates.io category slug
documentationwithtext-processingin the workspaceCargo.toml. - Moved prompt templates into
crates/brigid-pipeline/promptsso they are included in the publishedbrigid-pipelinecrate. - Made the release workflow's crates.io publish step idempotent, allowing re-runs to skip already-published workspace crates.
brigid 1.0.0
First stable release. brigid is a Rust CLI that crawls a codebase,
identifies its core abstractions via LLM map/reduce, and produces a
multi-chapter Markdown + Mermaid tutorial explaining how the system works.
Built for monorepos and large codebases where "read the source" is not a
realistic onboarding path.
This release consolidates Milestones 0–6 (the full Python-to-Rust migration
and Phase 5 foundation) plus the v1.0.0 documentation refactor and two
proposed ADRs for the post-1.0 roadmap (MCP server, graph provider
integration).
Added — v1.0.0 release
- Lean, user-focused README — rewritten from 686 to 184 lines with
Mermaid pipeline and output-structure diagrams, quick start, CLI table,
and links to deep documentation (#252). docs/usage-guide.md— deep command reference: every command, flag,
environment variable, provider setup (DeepSeek, OpenAI, Ollama, LM
Studio), performance tips, shell completions install, man page, examples
(#252).docs/troubleshooting.md— exit codes, checkpoint recovery, LLM/
cache/budget issues, corruption,--sincerequires git (#252).docs/project-status.md— milestones table (M0–M6), what works today,
roadmap including proposed MCP server and graph provider integration
(#252, #253, #255).- ADR 0015 — MCP server for codebase knowledge querying (proposed,
post-v1.0.0). Exposes the checkpoint knowledge graph as MCP resources/
tools/prompts so AI assistants can query on demand (#253). - ADR 0016 — Graph provider trait for structural ground truth from
codegraph/Graphify (proposed, post-v1.0.0). OptionalGraphProvider
trait to improve abstraction identification and relationship verification
on large codebases (#255). - Workspace layout moved into
ARCHITECTURE.mdnext to the crate
hierarchy diagram (#252). - AI code review automation and release/nightly CI documentation moved
intoCONTRIBUTING.md(#252).
Consolidated features (M0–M6)
The following capabilities were delivered across Milestones 0–6 and are
all included in this first stable release:
Pipeline (M0–M4):
- Full
brigid generatepipeline: crawl → identify → relationships →
order → chapters → setup → overview → combine - Map/reduce and single-shot LLM identify with bounded concurrency
- Checkpoint + resume (content-addressed, file-based stage outputs with
SHA-256 verification) - i18n chrome (English + Spanish)
--each-appmonorepo fan-out,--review-chapterssecond LLM pass- Score-triggered setup guide, multi-app architecture overview
Product polish (M5):
- Homebrew (source build),
cargo install,cargo-binstall, GitHub
Releases (Linux x86_64 binary; macOS/Windows compile from source) - Shell completions (bash, zsh, fish, PowerShell) and man page
- Disk cache with LRU eviction (enabled by default)
--concurrencyflag, criterion benchmarks,brigid initwizard- Windows CI, Python deprecation + migration guide
Phase 5 foundation (M6):
--format jsonon every stage with versionedStageOutput<T>envelope
(ADR 0012)--since <git-ref>git-diff incremental crawl (ADR 0013)- Plugin trait and registry for custom kind detectors (ADR 0014)
- Criterion benchmarks for all critical paths
- Audit-driven hardening of error handling, lock contention, test coverage
Changed — v1.0.0 release
- README.md rewritten: 686 → 184 lines, user-focused with Mermaid
diagrams, deep content moved to dedicated docs files (#252). - ARCHITECTURE.md updated: workspace layout tree added, ADR table
extended to 0016, related-documentation section updated (#252, #253,
#255). - CONTRIBUTING.md updated: AI code review automation section expanded
with CI/release/nightly workflow details, documentation section updated
(#252). - Version bumped from 0.6.0 to 1.0.0 — first stable release.
- Crates.io metadata added to all workspace crates (keywords,
categories) for publishing readiness. - Path dependencies now specify
version.workspace = truefor
crates.io publishing compatibility. - Release workflow (
.github/workflows/release.yml) now includes a
publish-cratesjob to publish all workspace crates to crates.io in
dependency order on tag push. - CI workflow (
.github/workflows/ci.yml) now includes:- Codecov upload — coverage reports (
lcov.info) are uploaded to
Codecov for trend tracking, PR comments, and badge integration
(requiresCODECOV_TOKENsecret). - actionlint — validates all GitHub Actions workflow files for
syntax errors and unsupported features. - Benchmarks — criterion benchmarks run on main pushes
(cargo bench --workspace -- --quick).
- Codecov upload — coverage reports (
codecov.yml— Codecov configuration with 85% project target
(matches the CI hard gate), 1% threshold for trend tolerance, and
fixture/benchmark/target directories excluded from reporting.- README badges — CI, Codecov, crates.io, and license badges added.
ADRs in this release
| ADR | Title | Status |
|---|---|---|
| 0001 | Content-addressed checkpoint format for resume | Accepted |
| 0002 | async-trait for the LlmClient trait |
Accepted |
| 0003 | tokio::sync::Semaphore for bounded map batches |
Accepted |
| 0004 | Migration off unsound serde_yml/libyml |
Superseded by 0005 |
| 0005 | Migration to serde_yaml_ng fork |
Accepted |
| 0006 | File-based stage output storage with SHA-256 verification | Accepted |
| 0007 | Generic localization framework for tutorial chrome | Accepted |
| 0008 | Two-tier golden fixture strategy for eval regression | Accepted |
| 0009 | Disk cache enabled by default with LRU eviction | Accepted |
| 0010 | Release strategy (GitHub Releases, Homebrew, cargo) | Accepted |
| 0011 | Python deprecation: migration guide over wrapper | Accepted |
| 0012 | JSON output schema (StageOutput<T> envelope) |
Accepted |
| 0013 | Git-diff incremental file detection (--since) |
Accepted |
| 0014 | Plugin trait and registry for custom kind detectors | Accepted |
| 0015 | MCP server for codebase knowledge querying | Proposed |
| 0016 | Graph provider trait for structural ground truth | Proposed |
Quality gates
cargo fmt --all -- --check— passcargo clippy --workspace --all-targets -- -D warnings— passcargo test --workspace— 1,157+ tests passcargo llvm-cov --workspace --fail-under-lines 85— 95.98% coverage- 3-OS CI matrix (Ubuntu, macOS, Windows) — all green
cargo audit+cargo deny— pass- Eval regression gate + fixture baseline check — pass