codegraph-brain

🧠 CGIS: Code Graph Intelligence System

A code graph your AI agent can query instead of guess

Ask "what breaks if I change this?" and get the call chain, not a guess.

CGIS parses a repository with tree-sitter into a graph of fully qualified symbols and the calls, imports and containment between them, stores it in SQLite, and serves it to AI agents over MCP. An agent that would otherwise grep and read whole files asks the graph instead.

• Languages: Python · TypeScript / TSX
• Runs: locally — no account, no telemetry; the graph never leaves your disk (the one opt-in exception)

$ cgis ingest src --output graph.db
$ cgis impact cgis.query.engine.QueryEngine.get_flow_graph --db graph.db --depth 2
🔍 Analyzing transitive upstream callers of: cgis.query.engine.QueryEngine.get_flow_graph

METHOD cgis.query.engine.QueryEngine.get_flow_graph (cgis/query/engine.py:215)
├── FUNCTION cgis.query.context.context_service._collect_callees (cgis/query/context/context_service.py:44)
│   └── FUNCTION cgis.query.context.context_service.build_context (cgis/query/context/context_service.py:96)
└── METHOD cgis.guardian.collector.ContextCollector._graph_sections (cgis/guardian/collector.py:174)
    ├── METHOD cgis.guardian.collector.ContextCollector.collect_graph_context (cgis/guardian/collector.py:213)
    └── METHOD cgis.guardian.collector.ContextCollector.collect_for_chunk (cgis/guardian/collector.py:303)

Real output — CGIS run on its own source.

🚀 Quickstart

In Claude Code (fastest)

/plugin marketplace add zaebee/codegraph-brain
/plugin install cgis@codegraph-brain

That ships the MCP server, a skill that teaches the agent when to query the graph instead of reading files, and /cgis:ingest to build the graph on first use. The server is pulled from PyPI on demand via uvx, so there is nothing to clone or build.

Any other MCP client (Cursor, Claude Desktop, …)

{
  "mcpServers": {
    "cgis": { "command": "uvx", "args": ["--from", "codegraph-brain", "cgis-mcp"] }
  }
}

From the terminal

# No install needed — uvx fetches it from PyPI
uvx --from codegraph-brain cgis ingest ./my-project --output graph.db

uvx --from codegraph-brain cgis impact "my_module.core_function" --db graph.db --depth 5   # who calls this
uvx --from codegraph-brain cgis trace  "my_module.MyClass.run"   --db graph.db --depth 3   # what this calls
# add --format mermaid (or json) to either for a diagram or machine-readable output

Or install it for good: pip install codegraph-brain (Python 3.12+), then use cgis directly. The full command list is in CLI_USAGE.md.

📈 Proof at Real Scale

CGIS runs on a working twelve-repository estate — four languages, 8,146 commits, shipping daily. On its FastAPI backend it classifies 82.7% of 87,845 edges definitively and prints the remaining 17.3% rather than inventing targets for them — including the part that is CGIS's own gap.

That share rose from 11.4% in #459, which stopped counting calls to missing symbols as resolved. About 4 points of what is left is a known resolver gap, not something undiscoverable: ingesting app/ strips the app. prefix its imports carry, and the import path does not yet reconcile the two — the same backend ingested at its package root reports 13.2%. The number is what the tool admits it cannot place today, and it is allowed to move the unflattering way.

Read the case study → — every figure measured and reproducible, including what CGIS doesn't cover.

🤔 Why a graph, and how this differs

Text retrieval hands an agent chunks that look related. It cannot say which of three functions named save a call reaches, or what sits five callers up. CGIS resolves every call site to a fully qualified name when the source allows it — and when it does not, the edge stays marked unresolved and is counted, never filled with a plausible guess.

If you use…	CGIS adds
grep / file reads in the agent	Transitive callers and callees in one call, without spending context on whole files
LSP-backed symbol tools (e.g. Serena)	A persisted whole-repo graph for multi-hop impact, coupling, PageRank and drift
A repo map (e.g. aider)	Resolved edges you can traverse and audit, with the resolved/unresolved ratio reported

🤖 MCP Tools

The main tools:

Tool	Answers
cgis_ingest	Build or incrementally refresh the graph
cgis_overview	Where to start: sizes and the largest packages, when you have no FQN yet
cgis_find_symbol	Partial name → candidate FQNs
cgis_analyze_impact	What breaks upstream if this changes?
cgis_trace_flow	What does this call, transitively?
cgis_get_structure	Class / module hierarchy
cgis_context	A compact GraphRAG context package for one symbol
cgis_metrics	Coupling, god classes, PageRank, package cohesion
cgis_audit_reachability	Authz / IDOR coverage — does every handler reach its guard?
cgis_drift	How far each domain has moved from its declared pattern
cgis_validate	Graph integrity: resolved vs unresolved edges

All 14 tools, with parameters: MCP_REFERENCE.md.

🏗️ How It Works

• Extract — tree-sitter parsers turn each file into nodes and raw call edges.
• Resolve — the ResolverEngine maps raw calls to fully qualified names, or leaves them explicitly unresolved.
• Store — SQLite holds the graph; queries are breadth-first traversals over it.

graph LR
    A[Source Code] --> B[Extractors]
    B --> C[Resolver Engine]
    C --> D[(SQLite Graph DB)]
    D --> E[MCP Server]
    D --> F[Prompt Compiler]
    E --> G[AI Agents]
    F --> G

The details — and a pipeline graph CGIS regenerates from its own source on every change — are in HOW_IT_WORKS.md.

🛡️ Guardian: Graph-Aware Code Review

Guardian is CGIS's built-in LLM reviewer — it reviews pull requests using the graph as context, not just the diff text. It runs in CI and posts inline comments anchored to the exact line.

• Two-stage, recall-first: a finder surfaces every plausible defect (optimised for recall), then a separate skeptic pass filters false positives — closer to how human reviewers work, and far more reliable than a single precision-gated prompt.
• Local or cloud, no lock-in: point it at Ollama (qwen2.5-coder, llama3.1, granite-code, …) for free local inference, or at Mistral / Gemini in the cloud. You can even mix them — a strong cloud finder with a free local cross-model skeptic.
• Graph-aware context: the reviewer sees impact graphs, architectural drift, and project ontology — so it catches structural and convention defects a flat-diff reviewer can't.
• Deterministic anchoring: every inline comment is positioned by a verbatim quote from the diff, not the model's (often wrong) line guess.
• Dogfooded & measured: Guardian reviews CGIS's own pull requests, and a benchmark harness scores it against curated ground truth — so prompt changes are validated, not guessed.

# Build the graph, then review a PR with a local model (no API key)
cgis ingest ./src --output graph.db
GUARDIAN_PROVIDER=ollama GUARDIAN_MODEL=qwen2.5-coder:14b \
  uv run python scripts/guardian_review.py --pr 123 --db graph.db --inline

No GPU on hand? Benchmark it on a notebook GPU → — free end to end, since the fixtures score without an LLM judge. Or point Guardian at a remote Ollama → — over an frp stcp tunnel, no public port, and a guard that refuses a review of a silently truncated prompt.

🔒 Privacy

CGIS collects nothing: no telemetry, no analytics, no account. Your code and the graph built from it stay on your machine. The one exception is opt-in: Guardian, if you run it with a cloud model, sends the reviewed diff to the provider you chose. See PRIVACY.md.

🛠️ Development

Requires Python 3.12+ and uv.

git clone https://github.com/zaebee/codegraph-brain && cd codegraph-brain
uv sync
make pytest

See CONTRIBUTING.md for the standards: strict MyPy, linting, ontology compliance.

💼 Architecture Audit

CGIS is free and you can run it yourself. If you would rather have the analysis than the tool, I run a fixed-price audit of your codebase's structure — authorisation coverage, blast radius, coupling, architectural drift — delivered in five working days, $2,400 fixed, with an explicit list of what the analysis cannot see. Read what's included →