**The black box for AI-written code.**
`git` tells you *what* changed. brain0 tells you *why*: which prompt wrote it,
what the agent **read** to write it, and whether you can trust it.
[](https://github.com/Brain0-ai/brain0/actions/workflows/ci.yml)
[](./LICENSE)
[](https://www.npmjs.com/package/brain0)
[](./crates)
[](./packages)
[](./CONTRIBUTING.md)
[Quickstart](#quickstart) · [What it answers](#the-questions-your-repo-cant-answer-today) ·
[Give your agent memory](#give-your-agent-the-why-layer-mcp) · [How it works](#how-it-works) ·
[Comparison](#how-it-compares) · [Docs](./docs)
---
Coding agents now write most of the diff: continuously, in parallel, and opaquely.
brain0 **passively** builds a decision graph of your repository: every **commit** linked to
the **agent intents** behind it, down to the single **function**, with dated history, drift
detection, a DLP audit of what agents *read*, and a two-dimensional **risk score** rendered
green → red. No hooks, no agent cooperation, no code changes: it reads git and the
transcripts your agents already write to disk.
> Dogfooded from day one: brain0's own development is tracked by brain0.
## Quickstart
```bash
npx brain0 up
```
That's it. From any repo, `up` infers the repo id from your git remote, indexes the git
history (the **facts**), passively ingests your coding-agent sessions (the **intents**,
with Codex and Claude Code auto-discovered), and opens the GUI at `http://localhost:8787`:
an explorable graph of your codebase, from repo to module, file and symbol, where clicking a
commit reveals the prompts behind it, per-file diffs, and risk at a glance.
Then make it a habit:
```bash
brain0 today # morning triage: what agents did, riskiest first
brain0 report # the accountability report (add --md to share it)
brain0 query "why did the parser break" # root-cause debug over the graph
```
## What you need
The only hard requirement is **Node.js ≥ 20** (on Linux, glibc ≥ 2.28: Debian 10+, Ubuntu
20.04+, RHEL 8+; musl/Alpine is not supported yet). brain0 is offline-first: with nothing else
installed it still works end to end: deterministic summaries, local feature-hash embeddings,
zero egress. Local models make it *better*, never *required*.
| Piece | Needed for | Without it |
|---|---|---|
| **Node.js ≥ 20** | everything (`npx brain0 up`) | (required) |
| **git** | commit history (the facts side) | filesystem checkpoint mode (`brain0 watch`) |
| **A coding agent**: Codex (`~/.codex`) or Claude Code (`~/.claude/projects`), auto-discovered | the *why* layer: prompts, drift, reads/DLP | graph of commits + code only |
| **[Ollama](https://ollama.com)** + models (below) | model-written summaries · semantic search · GUI smart chat | deterministic summaries · feature-hash embeddings · retrieval-only answers |
| `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` (opt-in) | a hosted LLM for the GUI smart chat | local Ollama (default) |
### Recommended local models
```bash
ollama pull qwen3:4b # summarizer (default)
ollama pull qwen3-embedding:0.6b # embeddings (default; nomic-embed-text is the auto-fallback)
```
Both run on modest hardware. On a small GPU (≈4 GB VRAM) use a lighter summarizer for the
first, cache-populating run. Summaries are content-cached in `~/.cache/brain0/`, so every
later rebuild costs zero model calls (and even an interrupted run keeps its work):
```bash
BRAIN0_SUMMARIZER_MODEL=qwen3:1.7b npx brain0 up
```
If a configured model is missing, brain0 tells you exactly what to pull and degrades
gracefully (embedder falls back to `nomic-embed-text`, then local). Every choice is
overridable: `BRAIN0_SUMMARIZER_{PROVIDER,MODEL,ENDPOINT}`, `BRAIN0_EMBED_{PROVIDER,MODEL,ENDPOINT,DIM}`,
`BRAIN0_LLM_PROVIDER`. Details in [`docs/models.md`](./docs/models.md).
## The questions your repo can't answer today
- *Which prompt introduced this bug?*
- *Who (agent or human) touched this function, when, and **why**?*
- *The agent claimed it "changed little." **Did it?***
- *Did any session read `.env` or a private key before pushing code?*
- *This change looked harmless. Did it later prove dangerous?*
brain0 answers all five, by construction. Three of those answers exist nowhere else:
### ① Drift: declared vs. done
Agents narrate what they changed; git records what actually changed. brain0 reconciles the
two and scores the gap. From brain0's own report:
```
drift — declared vs done (41)
· [1.00] claude-code — changed but not declared: crates/brain0-cli/src/main.rs,
packages/gui/src/main.ts … +12 more
```
### ② Sensitive reads: DLP for agent context
brain0 records which files each session **read** (paths and secret *kinds* only, never
values): explicit `Read` calls, `Grep` results, shell reads such as `cat .env` or `sed -n`,
and subagent transcripts, with the returned content scanned for secrets at ingest. The read
set comes from one source (the transcript the agent harness writes), so read it as a **lower
bound** of what reached a possibly-remote model, not a proof:
```
sensitive reads — DLP (7)
· claude-code read crates/brain0-agentsrc/src/driver.rs [env_secret]
· 8 read(s) outside the repo reached the model's context
```
### ③ Risk that learns: green → red
Every artifact carries an **a-priori** score (blast radius, churn, drift, diff size) fused
with an **a-posteriori** score fed by evidence (reverts, immediate fixes). A change that
*looked safe but later proved dangerous* is flagged as a **gold signal**: the pattern
worth studying.
## Give your agent the "why layer" (MCP)
The same graph is a query channel your coding agent can call **before touching code**:
provenance-aware context, by reference, nothing heavy pushed through MCP.
```bash
claude mcp add brain0 -- brain0 mcp
```
| Tool | What the agent learns |
|---|---|
| `brain0_context` | a file/symbol's risk, recent history, and the intents (agent · model · drift) behind it |
| `brain0_blame` | *which intent wrote this line*: `file:line` resolves to its symbol via live parsing |
| `brain0_debug` | root-cause candidates for an issue, recency- and risk-aware |
| `brain0_audit` | repo risk distribution, gold signals, riskiest nodes |
Your agent stops re-breaking what it can't remember. Uninstalling brain0 makes it
forget again.
## How it works
brain0 is a **pure observer**: it never touches your code or your git history. Its local
index lives in a `.brain0/` directory that ignores itself, and its keys live outside the
repository ([`docs/security.md`](./docs/security.md)).
```
┌───────────────────────── GUI (PixiJS / TS) ─────────────────────────┐
│ bipartite graph · LOD lens · risk color · timeline · search bar │
└───────────────▲─────────────────────────────────────▲───────────────┘
│ references / highlights │ on-demand
┌───────────────┴────────────┐ │ hydration
│ Internal agent (TS) │ │
│ RAG-on-graph · your LLM │ │
└───────────────▲────────────┘ │
│ index queries │
┌────────────────────────┴─────────────────────────────────────┴──────────────┐
│ Abstract storage (one `Storage` trait, pluggable backends) │
│ light index + embeddings | heavy payload (dedicated store) │
│ SQLite + sqlite-vec (local, open core) | Postgres + pgvector (enterprise) │
└────────────────────────▲──────────────────────────────────────────────────────┘
│ append-only (client-server)
┌────────────────────────┴─────────────────────────────────────────────────────┐
│ Core observer (Rust) │
│ git reader + fs-watcher / checkpoint engine (no-git fallback) [FACT] │
│ passive transcript + memory ingest (Codex, Claude Code, …) [DECLARED] │
│ Tree-sitter (symbol extraction + AST-fingerprint identity) │
│ declared↔done reconciliation (gap-filling + drift) │
│ a-priori risk · a-posteriori risk hooks (event-driven) │
└────────────────────────▲─────────────────────────────────────────────────────┘
│ passive read-only (no agent cooperation)
┌──────────┴───────────┐
│ Coding agents │ write transcripts + memory to disk;
│ (e.g. Codex, Claude)│ brain0 reads them, like it reads git
└──────────────────────┘
```
Principles that don't bend:
1. **Passive observation**: never modifies your repo, never commits/checks out, never interferes with git.
2. **The magnifying glass**: zooming descends into the *same* object (repo → module → file → symbol), never loads different nodes.
3. **No unjustified new nodes**: an entity that evolves stays the same node (deterministic, cross-machine symbol identity with rename/move tracking), with a dated chain of versions.
4. **Light index, lazy heavy payload**: the navigable graph is small and lasts for years; diffs, messages and summaries hydrate on demand.
5. **Open source and composable**: bring your own database and your own LLM keys, or run fully offline.
## How it compares
| | `git blame` | Vendor dashboards¹ | Git AI | **brain0** |
|---|:---:|:---:|:---:|:---:|
| Who committed a line | ✅ | ✗ | ✅ | ✅ |
| Which **prompt/intent** produced a change | ✗ | ✗ | ✅ | ✅ |
| Cross-agent, vendor-neutral | ✅ | ✗ | ✅ | ✅ |
| **Drift**: declared vs. actually done | ✗ | ✗ | ✗ | ✅ |
| What the agent **read** (incl. secrets, DLP) | ✗ | ✗ | ✗ | ✅ |
| **Risk score** per file/symbol, evidence-driven | ✗ | ✗ | ✗ | ✅ |
| Explorable **graph GUI** with time travel | ✗ | ✗ | ✗ | ✅ |
| Zero integration (no hooks in your agents) | ✅ | ✗ | ✗ | ✅ |
| Local-first, offline by default | ✅ | ✗ | ✅ | ✅ |
¹ Copilot Metrics API, Cursor team analytics, Claude Code analytics: per-vendor aggregates
(sessions, LoC accepted), no line/symbol-level provenance, no causality.
## Commands
| Command | What it does |
|---|---|
| `brain0 up` | index + observe + serve the GUI, one shot |
| `brain0 today` | last-24h triage, attention first (`--since 7d`) |
| `brain0 report` | drift · sensitive reads · top risk · agent footprint (`--md`) |
| `brain0 query "