| type | product-readme | ||
|---|---|---|---|
| title | BRAN | ||
| tags |
|
||
| resource | https://github.com/alphazede/bran |
BRAN is a local-first Rust CLI for deterministic code search: it ranks a repository offline and assembles a bounded context packet, so AI agents get the right files without searching for them. No embeddings and no index server. It runs fully offline, or connected to a model you choose — an API key is optional and unused by default.
rg answers "which lines contain this string." An agent asking "where is
authentication handled?" gets an unranked wall of matches and burns tokens
sorting it. BRAN answers "which files are authoritative for this question,"
ranked, with the reason attached.
| ripgrep / grep | Embedding RAG | BRAN | |
|---|---|---|---|
| Ranking | none | similarity | declared authority + path + body + metadata |
| Determinism | yes | no | yes — identical input, identical output |
| Needs a model | no | yes | optional — works either way |
| Needs an index server | no | usually | no |
| Reports a miss | n/a | rarely | yes, explicitly |
| Offline | yes | rarely | yes |
- The default total scan limit is now 256 MiB (was 64 MiB), so repositories with more than 64 MiB of scannable text no longer fail with
scan_error: LimitExceeded. The 1 MiB per-file and 10,000-file limits are unchanged. Existing derived indexes rebuild once because the scan configuration changed.
- Exact symbol navigation from existing SCIP indexes, with definitions, references, and implementations.
- Enterprise-document intake adapters for DOCX, XLSX, PPTX, and PDF, with citation anchors and explicit fidelity limits.
- Document evidence in
bran queryandbran packet: admitted DOCX, XLSX, PPTX, and PDF anchors come back with source type, native locator, source digest, fidelity, and derivation, andbran document inspectprints an envelope without writing anything. Documents that fail DLP or the public boundary are refused and never enter a packet. There is no OCR engine, so OCR stays unavailable. - A database evidence and state-store boundary that separates read-only evidence from derived state. Real database adapters and CLI wiring remain deferred; only the local file state backend is available.
- A staged deployment profile with registered-root mode for read-only remote CLI use. A service and an OCI image verified on a real base remain future work.
Prebuilt archives for Linux, macOS, and Windows are attached to the latest release (bran-v0.2.2):
https://github.com/alphazede/bran/releases/download/bran-v0.2.2/Or install bran-v0.2.2 from source:
cargo install --git https://github.com/alphazede/bran --tag bran-v0.2.2 bran-cliUnreleased features (
--brief,get --full):bran query --briefandbran get <id> --fullare unreleased until the next release afterbran-v0.2.2. Build from source onmainto run the short-first quickstart below:git clone https://github.com/alphazede/bran.git cd bran cargo build --release --locked -p bran-cli ./target/release/bran query . --brief "valid_sha256"
With a source build (unreleased until the next release after bran-v0.2.2), start with a short query to get ranked exact paths within a 2,000-character budget:
bran query . --brief "valid_sha256"{
"schema_version": "1.0.0",
"command": "query",
"status": "ok",
"data": {
"query_outcome": "grounded",
"query_coverage": { "matched_terms": ["valid_sha256"], "unmatched_terms": [] },
"coverage_basis": "sources",
"result_id": "sha256:...",
"selection": { "source": "rule" },
"results": [
{ "rank": 1, "path": "crates/bran-core/src/agent/runtime.rs", "reason": "exact:body" },
{ "rank": 2, "path": "crates/bran-core/src/agent/delegate.rs", "reason": "exact:body" },
{ "rank": 3, "path": "crates/bran-core/src/adapters/connected.rs", "reason": "exact:body" }
]
}
}Use --top N (default 8, max 32) to change depth. Paths are always exact; when an answer would exceed 2,000 characters, reason is shortened first down to the match kind (exact or partial) and query_coverage is bounded to fit. Repository scan diagnostics are summarized in a single scan_warnings line (warnings keeps brief-relevant items; run default bran query or bran get <id> --full for the full diagnostic list). Multi-root --brief queries (--add-dir) include "bundle" on each result item to distinguish identical relative paths across roots. coverage_basis is "sources" because brief mode derives outcome and coverage from source rankings without enterprise document evidence.
Expand a stored result from the query root:
bran get <result-id> # stored brief summary, question, and ranked paths
bran get <result-id> --full # full default query for the stored root and questionbran get <result-id> --full adds "stale: true" to warnings when the repository revision changed since the brief query ran. When .bran/ is absent or in registered-root mode, --brief still succeeds with result_id: null and a warning. Consuming repositories should add .bran/results/ to .gitignore so brief queries leave git status clean.
For a full follow-up directly (dependency closure, SCIP symbols, enterprise document evidence, and byte metrics):
bran query . "valid_sha256" | jq '{status, source_rankings: .data.source_rankings[:3], metrics}'{
"status": "ok",
"source_rankings": [
{ "rank": 1, "locator": "crates/bran-core/src/agent/runtime.rs", "match_reason": "exact:body" },
{ "rank": 2, "locator": "crates/bran-core/src/agent/delegate.rs", "match_reason": "exact:body" },
{ "rank": 3, "locator": "crates/bran-core/src/adapters/connected.rs", "match_reason": "exact:body" }
],
"metrics": {
"candidate_source_bytes": 2702707,
"selected_source_bytes": 133660,
"context_bytes_avoided": 2569047,
"estimated_tokens": 33415
}
}In default bran query output, selected_locators stays alphabetical (it is the dependency-closed set); relevance order is source_rankings in default query and results in query --brief. That is 2.7 MB of candidate sources narrowed to 134 KB.
An agent cannot tell a good answer from a confident wrong one. So when a high-specificity entity has no match, BRAN returns nothing and says why, instead of padding the result with files that matched the generic words around it:
bran query . "nonexistent-collector-xyz"{
"status": "ok",
"source_rankings": [],
"warnings": ["unmatched_query_terms: nonexistent-collector-xyz"]
}Command success is not evidence coverage. Empty results are a feature.
| Command | Purpose |
|---|---|
bran query <root> --brief [--top N] <request> |
Compact ranked paths (<=2,000 chars target) and a result_id |
bran query <root> <request> |
Full ranked sources, dependency closure, and evidence |
bran packet <root> <request> |
Assemble a bounded context packet |
bran check <root> <profile> |
Validate against okf-v0.1, okf-v0.2, or bran-strict |
bran maintain <propose|apply|revalidate> |
Bounded repair under explicit authority |
bran tui |
Browse the repository offline |
bran doctor --onboarding|--agent |
Read-only local readiness check |
bran get <result-id> [--full] |
Retrieve a stored result, or re-run the full query with --full |
Every command emits versioned JSON. query, packet, check, and tui need
no account and make no network calls.
BRAN ranks on declared authority, not guesswork. That declaration is the Open Knowledge Format, or OKF, Google's open spec. YAML frontmatter turns ordinary markdown into a queryable knowledge graph:
---
type: Concept
title: Ranking precedence
status: active
tags: [developer]
resource: https://github.com/alphazede/bran
---type is the only required field. Optional families cover provenance
(sources, usage_window), trust (generated, verified), and lifecycle
(status, stale_after).
bran check . okf-v0.2{
"selected_profile": "okf-v0.2",
"selected_passed": true,
"okf_compatibility": { "profile": "okf-v0.1", "status": "pass" },
"okf_v0_2": { "profile": "okf-v0.2", "status": "pass" },
"bran_strict": { "profile": "bran-strict", "status": "pass" }
}All three results are reported independently and only the selected profile
controls the exit code, so OKF conformance is never confused with house rules.
okf-v0.1 remains a supported selectable compatibility profile. okf-v0.2 is
additive and does not replace it. BRAN producer extensions (okf_status,
freshness, public_boundary) stay valid and are not silently renamed to
upstream status or stale_after.
bran_core::export emits an Obsidian-compatible vault from the graph, so a
repository can be browsed visually. See
examples/obsidian/usage.rs.
BRAN runs either way, and the same commands work in both modes.
Offline is the default and needs no account, no key, and no network. Scanning, ranking, packets, validation, and the TUI are complete on their own — this is not a trial tier.
Connected adds a model that reads what BRAN selected and answers with citations. It is opt-in per invocation.
If you connect a model, put it in the middle tier rather than the top:
- BRAN decides which files matter. Deterministic, offline, free.
- A fast or local model — a Flash-class model, or something on your own hardware — reads those files and condenses them.
- The frontier model receives that clean, bounded context and reasons.
The expensive model should never be the thing hunting through a repository. Retrieval is a search problem, not a reasoning problem.
BRAN has no API-key flag and never copies credentials. You point it at a profile; the account reference becomes an opaque one-way handle before any request, receipt, or diagnostic is written.
-
Create a project-local
.bran/settings.confwithprofile=connected-agent. -
Describe the connection through the environment — a reference, not a secret:
export BRAN_AGENT_PROFILE=<profile> export BRAN_AGENT_PROVIDER=<provider> export BRAN_AGENT_MODEL=<fast-or-local-model> export BRAN_AGENT_REASONING=medium export BRAN_AGENT_ACCOUNT_REF=<reference>
-
Check what is actually available before relying on it:
bran agents list bran doctor --agent
-
Run a bounded, grounded request:
bran -p --agent <profile> --reasoning medium --tools read,search \ --trust-current-root "which module owns frontmatter validation?"
--tools read,search limits it to repository read and search. --no-session
disables retention. --offline forces the deterministic profile even when a
profile is configured, so you can always fall back:
bran -p --agent <profile> --offline --no-session "offline return proof"If a capability is unavailable, BRAN says unavailable rather than pretending
it worked. Requested and effective capability are always reported separately.
This repository is the BRAN source. See CONTRIBUTING.md to build, test, and open a pull request. Report vulnerabilities privately through GitHub Security Advisories; do not open a public issue.
Giving an agent access is not enough. Without a reminder it reaches for
built-in search, which is always available and never reports unavailable.
Install skill/use-bran for the agent-facing
instructions, and see Agent setup for hook
recipes, reasoning and tool configuration, and the offline return check.
Each release uses an exact bran-vX.Y.Z tag. Downloads live under
https://github.com/alphazede/bran/releases/download/bran-vX.Y.Z/ — exact tags
only, never latest.
Five platform archives are published:
bran-vX.Y.Z-x86_64-unknown-linux-gnu.tar.gzbran-vX.Y.Z-aarch64-unknown-linux-gnu.tar.gzbran-vX.Y.Z-x86_64-apple-darwin.tar.gzbran-vX.Y.Z-aarch64-apple-darwin.tar.gzbran-vX.Y.Z-x86_64-pc-windows-msvc.zip
Alongside them: SHA256SUMS, SHA256SUMS.sigstore, and
bran-release-manifest.json, which records release provenance.
Signing is Sigstore keyless via GitHub OIDC — there is no long-lived key to manage or leak. Verify a download:
cosign verify-blob SHA256SUMS \
--bundle SHA256SUMS.sigstore \
--certificate-identity "https://github.com/alphazede/bran/.github/workflows/release.yml@refs/tags/bran-v0.2.2" \
--certificate-oidc-issuer "https://token.actions.githubusercontent.com"
sha256sum -c SHA256SUMS --ignore-missingSBOMs are not yet part of the release workflow.
Does BRAN need an API key? No. A key or auth session is entirely optional. Scanning, ranking, packets, validation, and the TUI are fully offline and make no network calls. A connected mode exists and is opt-in.
If I add a model, which one? A fast or local one. Use a Flash-class or self-hosted model to read the files BRAN selected and hand the condensed result to your frontier model. See Where the models go.
Does it replace RAG? For code and docs, often yes. It separates retrieval from reasoning, so a cheap deterministic step feeds the expensive model.
What languages does it support? Ranking is language-agnostic; it operates on paths, document bodies, structure, and OKF metadata.
Why did my query return nothing? Because nothing matched. Check the
unmatched_query_terms warning — that is BRAN refusing to guess.
Dual-licensed under MIT or Apache-2.0.