Purpose
codegraph-brain (also known as CGIS: Code Graph Intelligence System) is a code graph that "AI agents can query instead of guess." When an AI agent needs to ask "if I change this, what will break?", it returns the call chain instead of guessing. CGIS parses code repositories with tree-sitter, generates a graph composed of fully qualified symbols and the call, import, and containment relationships between them, stores the graph in SQLite, and exposes it to AI agents via MCP.
Main Capabilities
- Parsed languages: Python, TypeScript / TSX.
- Resolves each call site to a fully qualified name when the source code allows it; edges that cannot be resolved remain marked as unresolved and are counted, and are not filled in with plausible-looking guesses.
- Exposes the graph to AI agents via MCP.
- Built-in Guardian: a graph-aware code review tool that reviews Pull Requests using the graph as context, not just the diff text. Guardian runs in CI and posts inline comments anchored to exact lines.
- Two-stage, recall-first: the finder discovers all possible defects (optimized for recall), and an independent skeptic stage filters out false positives.
- Local or cloud LLM, no lock-in: can point to Ollama (qwen2.5-coder, llama3.1, granite-code, etc.) for free local inference, or to cloud-based Mistral / Gemini, and can also be used in a hybrid setup.
- Deterministic anchoring: each inline comment is located by a verbatim quote from the diff, rather than by the model's (often incorrect) line number guesses.
- See MCP_REFERENCE.md for all 14 tools and their parameters.
Usage
In Claude Code (fastest), installation provides an MCP server, a skill that teaches the agent when to query the graph instead of reading files, and /cgis:ingest for building the graph on first use. The server is pulled on demand from PyPI via uvx, with no cloning or building required.
Other MCP clients (Cursor, Claude Desktop, etc.) can also be used.
Use from the terminal: or install permanently: pip install codegraph-brain (Python 3.12+), then use cgis directly. See CLI_USAGE.md for the full command list.
How it works
- Extraction: the tree-sitter parser converts each file into nodes and raw call edges.
- Resolution: the ResolverEngine maps raw calls to fully qualified names, or explicitly marks them as unresolved.
- Storage: SQLite holds the graph; queries are breadth-first traversals over it.
See HOW_IT_WORKS.md for details and for the pipeline diagram that CGIS regenerates from its own source on every change.
When to use it
- Change impact analysis and call chain tracing.
- Multi-hop impact analysis, authorization reachability audits, coupling metrics, and architecture drift detection.
- AI agents replacing grep and reading entire files.
- Code review (Guardian) running in CI, detecting structural and convention defects based on graph context.
Limitations and caveats
- Requires Python 3.12+ and uv.
- Supported languages are limited to Python and TypeScript / TSX.
- For call edges that cannot be resolved, they are explicitly left unresolved and counted; there are known parser gaps (for example, ingesting at the application root strips the app. prefix carried by imports, and the reported percentage differs after ingesting at the package root).
- CGIS does not collect any data: no telemetry, no analytics, no accounts; code and graphs stay on the user's machine. The only exception is optional: if Guardian is run with a cloud model, the reviewed diff is sent to the chosen provider. See PRIVACY.md for details.
- Contribution standards are in CONTRIBUTING.md: strict MyPy, linting, ontology compliance.
Commercial audit service
The author also offers a fixed-price audit service for codebase structure: authorization coverage, blast radius, coupling, architecture drift, delivered within five business days, at a fixed price of $2,400, and listing what the analysis cannot see.
