GBrain Code

Selective, diff-aware repository cartography for coding agents.

GBrain Code answers one narrow question:

What code is related to this engineering task even when the relevant files do not use the same words?

It does not answer the engineering question, edit files, run an agent loop, or replace direct inspection and tests. It returns a versioned evidence map that an agent can verify with normal repository tools.

task
  -> question-scoped repository map
  -> agent opens decisive files
  -> agent edits and tests
  -> diff-aware ripple audit
  -> agent reviews omitted consumers, tests and duplicate candidates

Why

Model weights contain broad programming knowledge. They do not contain the current, private relationships unique to a changing repository: a React query calling an RPC patched by a later migration, a second consumer of the same table, or a test reached only through an imported callback.

Text search remains excellent for exact strings. GBrain Code complements it by following explicit structural edges and shared resources across files and layers.

Related MCP server: RepoNav

Public surface

The MCP server intentionally exposes only five tools:

• gbrain_status: verify snapshot freshness.

• map_code_context: retrieve anchors and expand their structural neighborhood.

• inspect_symbol: inspect definitions, callers, callees and SQL lineage.

• audit_code_change: map ripple candidates around the current Git diff.

• refresh_repository: update the local structural/text index.

There are no model consultants, answer generators, chat memories, or autonomous editing tools.

Current structural coverage

• TypeScript and JavaScript: modules, imports, definitions, calls, inheritance, overrides, Supabase RPC/table access (including small local wrappers such as callRpc(name, args)) and edge-function invocation.

• Python: modules, imports, functions, classes, methods, calls and inheritance when statically resolvable with ast.

• SQL: definitions, table access, function calls and ordered migration lineage.

• Other textual languages: bounded lexical and optional semantic retrieval; structural extraction remains future work.

Every map identifies its Git commit, working-tree generation and unresolved edges. An index that does not match the registered working tree fails closed. Repeated call sites are grouped by relationship and returned with line lists so the map spends its context budget on distinct evidence instead of duplication.

Install from source

Requirements: Python 3.11+, Git, Node.js and npm.

git clone https://github.com/spacerocket3/gbrain-code
cd gbrain-code
python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'
npm ci

Optional semantic retrieval:

.venv/bin/pip install -e '.[semantic]'

The default fast mode is lexical search plus structural graph traversal and never starts a model. Embeddings and code reranking are explicit experimental options through auto or code.

Register and index a repository

Registration is an explicit local authorization boundary. The MCP server cannot register arbitrary paths.

.venv/bin/gbrain-code project add my-repo /absolute/path/to/my-repo
.venv/bin/gbrain-code index my-repo

# Optional semantic index
.venv/bin/gbrain-code embed my-repo

Runtime state is ignored by Git and defaults to:

• registry: data/projects.json

• SQLite evidence index: data/index.sqlite3

• model cache: ~/.cache/gbrain-code/models

Override these with GBRAIN_PROJECTS_FILE, GBRAIN_DB and GBRAIN_MODEL_CACHE.

Query locally

.venv/bin/gbrain-code map my-repo \
  "change reservation retries without breaking duplicate protection"

.venv/bin/gbrain-code inspect my-repo update_reservation

# After editing, refresh before auditing the working-tree diff
.venv/bin/gbrain-code index my-repo --force
.venv/bin/gbrain-code audit my-repo --question \
  "change reservation retries without breaking duplicate protection"

MCP registration

codex mcp add gbrain-code -- \
  /absolute/path/to/gbrain-code/.venv/bin/python \
  /absolute/path/to/gbrain-code/mcp_server.py

GBrain Code is intentionally opt-in. A repository or agent policy should decide when a task is large enough to justify cartography.

Evidence contract

• A graph edge means the extractor observed a static relationship.

• An unresolved edge is retained and labelled, not silently promoted.

• A ripple candidate means “inspect this,” not “this is broken.”

• A same-name symbol is not proof of duplicate code.

• active=0 means a repeated SQL definition was superseded by a later migration.

• Direct source inspection, Git history and executable tests remain authoritative.

Research and evaluation

• Position paper

• Architecture

• Prior art and boundaries

• Evaluation protocol

• Reactive Repository State experiment

• Dual-snapshot Repository Twin Lab

• Executable Impact Simulation Lab

The repository includes file-retrieval evaluators, experimental impact propagation, a dual-snapshot Repository Twin and an equal-budget executable scheduling lab. The Twin preserves relationships removed by a change and emits source-cited review candidates instead of presenting graph paths as causal impact. All reactive components remain outside the MCP surface.

The Repository Twin experiment additionally compares normalized T0 and T1 graphs so a post-change audit can retain relationships deleted by the diff. Its controlled microrepository proves that mechanical capability. A single exploratory same-model agent pilot also produced a better frozen-test outcome with the Twin packet, but is explicitly reported as n=1, synthetic and not causal evidence.

The executable scheduling lab takes one additional step: it uses the Twin ranking to allocate an equal budget of real differential checks. Its first public synthetic case improves regression discovery from 35.1% under seeded general scheduling to 100%, while explicitly making no GPU, model or general benchmark claim.

This publication stops at faithful structural evidence and executable verification. It does not include automatic semantic translation, model consultation, autonomous editing or a claim that the graph can decide which code must change. Those are separate research questions, not hidden product features.

Status

Experimental alpha. The core behavior is tested, but no claim of superiority over repository maps, embeddings, or agent exploration is made until controlled evaluation is published.

License

Apache-2.0. See LICENSE and NOTICE.