Symbols
What the file defines
Functions, classes and exported names, each anchored to the line span where it is declared rather than described in prose.
BNLGit · For engineers
Exact context, or an honest refusal.
BNLGit does not change your model — it changes what your model sees. Every file gets a summary twin in a real git repository beside your source, every fact is anchored to a line span at a pinned commit, and every span is re-checked against the actual blob before it reaches your agent.
The retrieval path
What your agent actually gets back.
A search hit is an evidence bundle, not a snippet. That distinction is the whole product.
Typed facts
Not a paragraph about the file. A structured record of it.
Each summary twin holds a readable summary and a block of typed facts. Every one of them is anchored to a line span in a specific blob at a specific commit.
Imports
What it depends on
The modules and packages a file pulls in, so an agent can walk a dependency edge instead of grepping for it.
Endpoints
What it exposes
API routes and handlers surfaced as typed facts, so "where is this endpoint served" is a lookup, not a search.
Entities
What it stores
Database entities the file touches — the layer that usually lives only in a migration folder and someone's memory.
Effects
What it changes
Side effects worth knowing about before an agent proposes an edit: writes, network calls, process and filesystem work.
Security
What to be careful with
Security-relevant concerns flagged on the file that carries them, plus the related files a change is likely to ripple into.
The trust ladder
Results are ranked by how much they deserve to be believed.
You have to ask for the untrustworthy material on purpose. That is the design.
| Tier | Meaning | By default |
|---|---|---|
verified_current |
Highest — the summary matches the current source blob. | Included |
code_only_current |
Source matched; there is no current summary. | Included |
legacy_unverified |
Imported before BNLGit; provenance unverified. | Excluded |
verified_stale |
Summary matched, but the source has since changed. | Excluded |
unavailable |
Excluded by default. | Excluded |
Pass include_stale or include_unverified to opt back in.
MCP surface
Two read-only servers: one repository, or the whole fleet.
Four repo-scoped tools and two fleet-scoped ones. They do not widen what a token can reach — they are a different way to ask the same permission system the same question.
Repository scope
POST /api/v1/repos/{owner}/{repo}/bnlgit/mcp
- fetch_bnlgit_overview
- search_bnlgit_documentation
- search_bnlgit_code
- search_bnlgit_hybrid
Code-read access to that repository.
Fleet scope
POST /api/v1/bnlgit/mcp
- list_bnlgit_repos
- search_bnlgit_hybrid
The repository token scope. Limited to whatever its owner can already see.
Reference
The mechanics, without the marketing.
| Pairing | Pair a repository and BNLGit creates a second, real git repository beside it holding one summary twin per source file. |
|---|---|
| Anchoring | Every fact points at a line span in a specific blob at a specific commit — not at a file in the abstract. |
| Re-validation | Line spans are re-checked against the pinned blob before they are returned. A span pointing at line 240 of a file that is now 180 lines long is caught, not silently mis-served. |
| Staleness | When the source moves on, the summary is marked stale and down-ranked. Stale and unverified results are excluded unless you opt back in. |
| Lexical search | Exact and fuzzy text search across summaries. Available on every paired repository, always. |
| Exact code search | Exact search over your real source files, backed by git grep. Exposed to agents as search_bnlgit_code. |
| Result packing | Packed to a token budget: 8 results and 6000 tokens by default, raisable to 25 and 32000. A summary_only mode returns excerpts without the backing source. |
| Wire protocol | JSON-RPC 2.0 over HTTP POST, MCP protocol version 2025-06-18. Methods: initialize, ping, tools/list, tools/call. No SSE or streaming transport. Request bodies capped at 2 MiB. |
| Authentication | A normal Gitea personal access token — Authorization: token <t>, or Bearer, which is what most MCP clients send. Access is enforced per request, on every read. |
| Capabilities | GET /api/v1/bnlgit/capabilities needs no authentication and returns the running edition, licence status, feature-flag map and drift thresholds. Scripts and agents should read this rather than assume. |
| Fail-closed editions | An instance configured with an edition value it does not recognise resolves to Lite, not Pro. There is no configuration typo that accidentally unlocks paid features. |
BNLGit publishes no performance benchmarks, because none have been run that it would be willing to defend. The argument for it is a mechanical one, not a leaderboard.
Point an agent at it and see what changes.
The documentation is public and needs no account. Start with the MCP guide if you want to wire a client up in ten minutes.