🧠 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
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
uvx --from codegraph-brain cgis trace "my_module.MyClass.run" --db graph.db --depth 3
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 |
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.
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 →