Brigid — Rust CLI for LLM-Generated Codebase Tutorials

A memory-safe Rust CLI that turns any codebase into a beginner-friendly, LLM-generated tutorial.

brigid crawls a codebase, identifies its core abstractions, and produces a multi-chapter Markdown + Mermaid tutorial that explains how the system works: setup, architecture, and inter-concept relationships. It is built in Rust and designed for monorepos and large codebases where "read the source" is not a realistic onboarding path.

Who this is for: teams, educators, and open-source maintainers who need onboarding tutorials generated from real code.

flowchart LR
    A["Crawl\nfiles"] --> B["Identify\nabstractions"]
    B --> C["Map\nrelationships"]
    C --> D["Order\nchapters"]
    D --> E["Write chapters\n+ diagrams"]
    E --> F["Setup\nguide?"]
    F --> G["Architecture\noverview?"]
    G --> H["Combine\nindex"]
    H --> I["Tutorial\noutput"]

Every expensive stage is checkpointed — interrupt with Ctrl+C and re-run to resume from the last completed stage. No work is lost.

# Homebrew (macOS)
brew tap igmarin/homebrew-tap
brew install brigid

# cargo install
cargo install brigid-cli

# cargo-binstall (pre-built Linux binary, compiles from source on macOS/Windows)
cargo binstall brigid-cli

Or download the Linux binary from GitHub Releases.

Verify: brigid --version

# 1. Set your LLM API key (DeepSeek is the default provider)
export DEEPSEEK_API_KEY="sk-your-key-here"

# 2. Generate a tutorial from any codebase
brigid generate --dir ./my-project --output-dir ./tutorial

# 3. Open the result
open ./tutorial/index.md

That's it. The tutorial is plain Markdown with Mermaid diagrams — render it in any Markdown viewer (GitHub, VS Code, Obsidian).

No API key? Set BRIGID_FORCE_MOCK=1 to run the full pipeline with a mock LLM client for offline testing.

flowchart TB
    subgraph "Tutorial output"
        IDX["index.md\n— table of contents\n— system overview\n— navigation links"]
        CH["chapters/\n— one file per abstraction\n— Mermaid diagrams\n— real file paths"]
        SETUP["setup.md\n— local setup steps\n— gap assessment"]
        OVERVIEW["overview.md\n— architecture diagram\n— cross-cutting concerns"]
    end

Each chapter references real file paths from your repo and includes Mermaid diagrams that visualize the concept. The setup guide fills gaps when official docs are thin. The architecture overview ties everything together for monorepos and multi-app systems.

• Full pipeline — crawl → identify → relationships → order → chapters → setup → overview → combine
• Tutorial styles — --tutorial-style blog|book (blog is default: shorter, conversational; book: long-form reference)
• JSON output — --format json on every stage for CI and editor plugins
• Incremental — --since <git-ref> only re-analyzes changed files and re-generates only chapters whose abstractions touched those files
• Monorepo support — --each-app generates one tutorial per app
• i18n — --language en|es localizes tutorial chrome
• Chapter review — --review-chapters adds a second LLM pass per chapter
• Lenient app validation — unknown apps warn by default; --strict-app-validation to fail hard
• Checkpoint + resume — interrupt and resume without losing work
• Disk cache — LLM responses cached on disk; re-runs are free. Inspect with brigid cache stats, clear with brigid cache prune
• Plugins — custom kind detectors via KindDetector trait (ADR 0014)

For every flag, environment variable, and provider configuration, see the Usage Guide.

brigid init writes a starter brigid.toml. Precedence is CLI > file > env > defaults.

max_llm_calls = 200
max_abstractions = 30

[plugins]
dirs = ["./plugins"]

Run brigid init --check to validate an existing config.

For recovery procedures, common issues, and fixes, see Troubleshooting.

MIT