brain0

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.

[CI] [License: Apache-2.0] [npm] [Rust] [TypeScript] [PRs Welcome]

Quickstart · What it answers · Give your agent memory · How it works · Comparison · 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

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:

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.

Recommended local models

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):

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.

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.

claude mcp add brain0 -- brain0 mcp

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).

            ┌───────────────────────── 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

¹ Copilot Metrics API, Cursor team analytics, Claude Code analytics: per-vendor aggregates (sessions, LoC accepted), no line/symbol-level provenance, no causality.

Commands

Building from source

Prerequisites: Rust (see rust-toolchain.toml), Node 20+, pnpm.

cargo build && cargo test          # Rust core (14 crates)
pnpm install && pnpm -r build && pnpm -r test   # TS workspace (shared · agent · gui · server)
./scripts/e2e.sh                   # cross-language end-to-end check

# All-in-one dev loop (build → ingest → observe → server :8787 → GUI :5173)
pnpm dev --repo myorg/myrepo

The GUI's Refresh button re-runs the same passive observer and re-embeds, live; it is served same-origin on 127.0.0.1 only.

crates/      Rust core (model, parser, identity, storage, observer, reconcile, risk,
             agentsrc, crypto, models, policy, attest, mcp, cli)
packages/    TypeScript (shared, agent, gui, server, cli)
schema/      SQL DDL for the local SQLite backend
docs/        Documentation (agent-artifact schemas, security, models, open-core, governance)

Privacy & security, by default

• Offline by default: no keys ⇒ local embeddings + local models (Ollama optional); nothing leaves the machine. Remote LLM/embeddings are an explicit opt-in, with context redacted before egress.
• Secret scanning at ingest: transcripts are scanned and redacted (typed placeholders, never values) before anything is stored, summarized, or embedded; BRAIN0_EXCLUDE / BRAIN0_REDACT add your own rules. The raw prompt text is not persisted; only the model-generated summary.
• Encrypted at rest: envelope-encrypted payload store (ChaCha20-Poly1305, KEK rotation, crypto-shred purge) with restrictive file permissions.
• Append-only, content-addressed: the graph is tamper-evident (brain0 verify), with an append-only security audit log.
• Reads are single-source, and pinned: git is an independent witness for what agents wrote; nothing plays that role for what they read, which comes only from the harness transcript. brain0 pins every ingested transcript range (BLAKE3 in the audit log) and brain0 verify re-checks it, so a transcript altered after ingest is caught; one altered before ingest is not. What a fact-side source would take: docs/governance.md.

Threat model and honest limitations: docs/security.md.

Open core

Everything in this repository is free and open source under Apache-2.0 and fully functional on its own, with no license checks, feature flags, or crippled code paths. Team/hosted capabilities (a PostgreSQL + pgvector backend implementing the same public brain0_storage::Storage trait, signed entitlements, a multi-tenant server) live in a separate brain0-enterprise repository (AGPLv3 + commercial). brain0 never depends on brain0-enterprise. Full boundary and rationale: docs/open-core.md.

Contributing

See CONTRIBUTING.md. By participating you agree to the Code of Conduct. Contributions are accepted under our CLA (see cla/), which keeps the open-core dual-licensing sustainable.

License

Apache-2.0 © The brain0 Authors.