brain0: A Decision Graph for AI-Written Code

What brain0 answers that git cannot

Git records what changed. It does not record which prompt asked for the change, what the agent read before writing it, or whether a change that looked harmless later turned out to be dangerous. brain0 is built around those three gaps. The README frames the project as "the black box for AI-written code," and the questions it lists are concrete: which prompt introduced this bug, who or what touched this function and why, did the agent's claim of a small change match the diff, did any session read .env or a private key before pushing code.

The audience is teams where coding agents write a large share of the diff and where review now means reading output whose intent is invisible. brain0 is passive: the README states there are no hooks, no agent cooperation, and no code changes. It reads git history and the transcripts agents already write to disk. That design choice sets both its reach and its ceiling, because anything the agents do not record is outside the graph.

How the decision graph is built: facts, intents, and drift

The graph has two sides. The facts side comes from git history and from parsing source with tree-sitter, which is why the Rust workspace lists tree-sitter grammars for Python, TypeScript, JavaScript, and Rust. The intents side comes from agent sessions, with Codex and Claude Code auto-discovered from ~/.codex and ~/.claude/projects according to the README. The graph is explorable from repo down to module, file, and symbol.

Drift detection reconciles the two sides. Agents narrate what they changed; git records what actually changed; brain0 scores the gap. The README shows an example from the project's own report, where a claude-code session changed crates/brain0-cli/src/main.rs and packages/gui/src/main.ts without declaring them, scored at 1.00. That is the mechanism worth understanding: drift is not a lint rule, it is a comparison between two records that already exist.

The DLP layer records which files each session read, storing paths and secret kinds only, never values, and scanning returned content for secrets at ingest. The README is explicit that the read set comes from one source, the transcript the agent harness writes, so it should be read as a lower bound of what reached a possibly-remote model, not as proof. Risk combines an a-priori score from blast radius, churn, drift, and diff size with an a-posteriori score fed by evidence such as reverts and immediate fixes. A change that looked safe and later proved dangerous is flagged as a gold signal.

Installing brain0 and running a first triage

The only hard requirement is Node.js 20 or newer. The README gives a single command, run from any repository, which infers the repo id from the git remote, indexes history, ingests agent sessions, and opens a GUI on port 8787.

npx brain0 up

After that, the README suggests three habits. The first is a morning triage that lists what agents did, riskiest first:

brain0 today

The second produces an accountability report, with a --md flag for sharing:

brain0 report --md

The third is root-cause debugging over the graph:

brain0 query "why did the parser break"

Local models are optional but change what you get. With Ollama installed, the README recommends pulling a summarizer and an embedder:

ollama pull qwen3:4b
ollama pull qwen3-embedding:0.6b

Without them, brain0 still works end to end with deterministic summaries and local feature-hash embeddings, and the README states there is zero egress. Summaries are content-cached in ~/.cache/brain0/, so later rebuilds cost no model calls. On a small GPU the README suggests a lighter summarizer for the first cache-populating run, set through an environment variable:

BRAIN0_SUMMARIZER_MODEL=qwen3:1.7b npx brain0 up

One more piece is worth trying early. The same graph is exposed to coding agents over MCP, which the README demonstrates with Claude Code:

claude mcp add brain0 -- brain0 mcp

That registers tools such as brain0_context, brain0_blame, brain0_debug, and brain0_audit, so an agent can ask what risk and intents sit behind a file before editing it. brain0_blame resolves a file:line to its symbol through live parsing.

Where brain0 is blind or the wrong tool

The largest limitation is stated plainly in the README: the DLP read set is a lower bound, not proof. If an agent read a secret through a path the harness did not log, brain0 will not know. A team that needs a hard guarantee about what left the machine should not treat this as that guarantee.

The second limitation follows from the passive design. Without agent transcripts, the graph collapses to commits and code. The README's own requirement table says exactly that: without a coding agent, you get a graph of commits plus code, and no why layer. So a repository where humans write the diffs gains much less than one where agents do. Similarly, without git, brain0 falls back to a filesystem checkpoint mode through brain0 watch, which is a different and thinner record than history.

There is also a resource question. Model-written summaries, semantic search, and the GUI smart chat need Ollama and models; the README notes both run on modest hardware and suggests a lighter summarizer on a roughly 4 GB VRAM GPU. Hosted providers are opt-in through ANTHROPIC_API_KEY or OPENAI_API_KEY, and the .env.example states that context is redacted before egress and shown in the UI. Embeddings are a second egress channel and default to local even when an OpenAI key is present. Teams with strict data rules should read those two defaults carefully before setting any key.

How brain0 compares with commit trailers and review tools

The closest alternative is not another observability product but a convention: asking agents to write structured commit trailers that name the model and the prompt. That approach costs nothing to run and travels with the commit, but it depends on agent cooperation, and the README's whole premise is that brain0 needs none. Trailers also record only what the agent chose to declare, which is precisely the claim drift detection exists to check.

A second alternative is a review or static-analysis pipeline that scores diffs by size and churn. That gives an a-priori signal similar to part of brain0's risk score, but it has no a-posteriori half, so it cannot flag the change that looked safe and later proved dangerous. The gold-signal concept depends on keeping evidence after the fact, which a pre-merge check does not do.

brain0's own trade-off is the inverse: it is passive, so it sees only what git and the transcripts contain, and it brings a local index, a SQLite store, and a GUI where a trailer convention brings nothing. The repository layout supports that reading, with separate crates for storage, reconcile, risk, policy, attest, and mcp.

Maintenance, upgrades, and the Apache-2.0 licence

The last push to the default branch was on 2026-09-09, and the most recent release is v0.1.1 from the same day, following v0.1.0 on 2026-07-02. The version is 0.1.x, so expect interface churn: the README documents environment variables such as BRAIN0_SUMMARIZER_PROVIDER, BRAIN0_EMBED_DIM, and BRAIN0_LLM_PROVIDER, and any of those names can move before 1.0. The repository is not archived.

Upgrade cost is low in one respect and non-trivial in another. The npm package is the entry point, so a new version arrives with npx, and the README states that summaries are content-cached in ~/.cache/brain0/, which means a rebuild after an upgrade does not necessarily repeat model calls. The non-trivial part is the local state: the Rust workspace pins rusqlite with the bundled feature and ships crates for storage and identity, so a schema change between versions can require a reindex.

The licence is Apache-2.0 for the workspace, and the root package.json carries the same identifier. That permits commercial use and modification, and it includes an explicit patent grant. It also means anyone can fork and redistribute, so a signed attestation from a fork is not the same object as one from this project. This is a description of the licence text, not legal advice; teams with compliance requirements should have counsel read it.

Editorial conclusion

brain0 fits teams whose diffs are now mostly agent-written and who need to answer which prompt introduced a bug, what a session read, and whether a change that looked safe later proved dangerous. It is the wrong tool if you have no coding-agent transcripts on disk, since without them you get a graph of commits and code only, with no why layer. Before adopting, verify that your agents write transcripts where brain0 looks, that Node.js 20 or newer is available, and whether you accept Apache-2.0 terms for the CLI and the npm package.

Frequently asked questions

Official sources

1. Brain0-ai/brain0 on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases