Skip to content
This repository was archived by the owner on Oct 15, 2026. It is now read-only.

Releases

brigid 2.1.0

Choose a tag to compare

@github-actions github-actions released this 19 Aug 00:09

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 prune subcommand: 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 a BEGIN IMMEDIATE transaction, then COMMIT; (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 -rf workaround.
  • Added brigid cache stats subcommand: 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: a KvStore wrapper that
    counts cache hit/miss statistics at the store level. When CacheClient
    calls store.get(key), the CountingKvStore counts Some as a hit and
    None as a miss. This is the correct layer for cache statistics — no
    duplicated cache-key derivation, no race conditions, no extra KV lookups.
    Exports CacheStats, CacheStatsHandle, and CountingKvStore from
    brigid_pipeline. Wired into build_live_client so the CLI's generate
    and generate --each-app verbose output reports cache hit/miss counts
    and hit rate.
  • Added brigid_pipeline::CacheAdmin: admin operations on a
    SqliteKvStore cache 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 direct rusqlite dependency.
    The brigid cache prune and brigid cache stats subcommands delegate to
    these methods.
  • Moved rusqlite dependency from brigid-cli to brigid-pipeline.
    The CLI is now a thin wiring layer that calls CacheAdmin methods.
  • Updated BRIGID_NO_CACHE help text to mention brigid cache prune and
    brigid cache stats.

Phase 4: brigid-llm removal (issue #297)

  • Removed brigid-llm crate from the workspace. The CLI now uses
    llm_kernel::llm::{OpenAIClient, RetryClient, CacheClient} directly — no
    adapter layer.
  • The LegacyLlmClient adapter, legacy_llm_error mapping, and
    brigid_llm::DiskCache have been replaced with llm_kernel native types.
  • Provider resolution logic moved to brigid_pipeline::llm as
    resolve_llm_config and build_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: OpenAIClient is now wrapped in llm_kernel::RetryClient
    with the default RetryConfig (max 3 retries, 1s base delay, exponential
    backoff, Retry-After capped at 5 minutes). This matches the bounded
    exponential backoff guarantees of the removed brigid-llm client.
  • Cache backend changed from brigid_llm::DiskCache (file-based with LRU
    eviction and size limits) to llm_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 set BRIGID_NO_CACHE=1 to 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 counts KvStore lookups.
      The CLI's verbose output reports cache status; use brigid 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.
  • Removed async-trait dependency from brigid-cli (no longer needed without
    the adapter).

brigid 1.3.0

Choose a tag to compare

@github-actions github-actions released this 07 Aug 15:06

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-mcp crate 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 rmcp crate (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.
  • Graph Provider abstraction (ADR 0016). New GraphProvider trait in
    brigid-core allows external structural analysis tools (call graphs, code
    knowledge graphs) to enhance brigid's pipeline with structural data. The
    NoneProvider is 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
      Relationship records 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.
  • GraphProviderConfig in RunConfig — configurable via [graph_provider]
    in brigid.toml, BRIGID_GRAPH_PROVIDER environment variable, and CLI.
    Supports type = "none" (default) and type = "codegraph" with a data_path
    pointing to a CodeGraph SQLite database.

Changed

  • New brigid-mcp crate added to the workspace. Does not affect existing
    crates — the MCP server is a separate binary that reads checkpoints produced
    by brigid generate.

brigid 1.2.0

Choose a tag to compare

@github-actions github-actions released this 30 Jul 17:56

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, or BRIGID_PROVIDER / BRIGID_MODEL. Defaults to
    https://openrouter.ai/api/v1, allowlists openrouter.ai, accepts
    OPENROUTER_API_KEY, and sends OpenRouter attribution headers. RunConfig.provider
    and RunConfig.model now drive live client construction for all presets
    (DeepSeek, OpenAI, OpenRouter, custom).

Changed

  • RunConfig.provider and RunConfig.model are now operational. These
    fields were previously parsed from brigid.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-chat as 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

Choose a tag to compare

@github-actions github-actions released this 29 Jul 16:39
a7680d8

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) and book (the previous long-form style). The flag
    selects the chapter outline and architecture overview templates. The
    TutorialStyle enum is threaded through RunConfig, GenerateConfig,
    ChaptersConfig, and OverviewInput (#267, #270).
  • --strict-app-validation flag. 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 --since is 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 a HashSet for
    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 --dir differs. The source_dir field is
    now included in the checkpoint's config_hash identity 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_tokens to prevent truncation (#262, #263).
  • Relationship endpoint range-checking. Follow-up tests for PR #259:
    relationship endpoint tests, mock fallback warning, and FORCE_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 caused NotFound errors (#271).

brigid 1.0.2

Choose a tag to compare

@github-actions github-actions released this 28 Jul 04:26
cb21ae0

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
    returns Result instead of Option; when no BRIGID_LLM_API_KEY /
    DEEPSEEK_API_KEY is set and BRIGID_FORCE_MOCK is 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 set BRIGID_FORCE_MOCK=1 explicitly.
  • BRIGID_FORCE_MOCK recognizes 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.md policy with supported-versions statement and private
    vulnerability reporting instructions via GitHub Security Advisories.
  • Relationship endpoint range-checking. The relationships stage now
    validates that from_abstraction / to_abstraction indices fall within
    the identify result, returning RelationshipsError::EndpointOutOfRange
    instead of panicking on malformed LLM output.
  • Centralized mock placeholder responses. The PLACEHOLDER_* constants
    and mock_client helper are now shared across cmd_identify,
    cmd_generate, and cmd_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-shot mock path,
    --each-app --review-chapters, and --each-app --force-setup branches.

Fixed

  • Codecov patch coverage on PR #259: 84.61% → 89.11% (target: 85%).

brigid 1.0.1

Choose a tag to compare

@github-actions github-actions released this 27 Jul 20:43

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 main brigid repository.
  • readme = "README.md" entry in each crate Cargo.toml so crates.io renders the README.

Fixed

  • Replaced the unsupported crates.io category slug documentation with text-processing in the workspace Cargo.toml.
  • Moved prompt templates into crates/brigid-pipeline/prompts so they are included in the published brigid-pipeline crate.
  • Made the release workflow's crates.io publish step idempotent, allowing re-runs to skip already-published workspace crates.

brigid 1.0.0

Choose a tag to compare

@github-actions github-actions released this 27 Jul 20:10

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, --since requires 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). Optional GraphProvider
    trait to improve abstraction identification and relationship verification
    on large codebases (#255).
  • Workspace layout moved into ARCHITECTURE.md next to the crate
    hierarchy diagram (#252).
  • AI code review automation and release/nightly CI documentation moved
    into CONTRIBUTING.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 generate pipeline: 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-app monorepo fan-out, --review-chapters second 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)
  • --concurrency flag, criterion benchmarks, brigid init wizard
  • Windows CI, Python deprecation + migration guide

Phase 5 foundation (M6):

  • --format json on every stage with versioned StageOutput<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 = true for
    crates.io publishing compatibility.
  • Release workflow (.github/workflows/release.yml) now includes a
    publish-crates job 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
      (requires CODECOV_TOKEN secret).
    • 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.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 — pass
  • cargo clippy --workspace --all-targets -- -D warnings — pass
  • cargo test --workspace — 1,157+ tests pass
  • cargo 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