kinrg 1.0.3

Persistent incremental knowledge graph for token-efficient, context-aware code reviews with Claude Code

kinrg

Stop burning tokens. Start reviewing smarter.

AI coding tools re-read your entire codebase on every task. kinrg fixes that. It builds a structural map of your code with Tree-sitter, tracks changes incrementally, and gives your AI assistant precise context via MCP so it reads only what matters.

---

Quick Start

pip install kinrg                     # or: pipx install kinrg
kinrg install          # auto-detects and configures all supported platforms
kinrg build            # parse your codebase

One command sets up everything. install detects which AI coding tools you have, writes the correct MCP configuration for each one, and injects graph-aware instructions into your platform rules. It auto-detects whether you installed via uvx or pip/pipx and generates the right config. Restart your editor/tool after installing.

To target a specific platform:

kinrg install --platform codex       # configure only Codex
kinrg install --platform cursor      # configure only Cursor
kinrg install --platform claude-code  # configure only Claude Code

Requires Python 3.10+. For the best experience, install uv (the MCP config will use uvx if available, otherwise falls back to the kinrg command directly).

Then open your project and ask your AI assistant:

Build the code review graph for this project

The initial build takes ~10 seconds for a 500-file project. After that, the graph updates automatically on every file edit and git commit.

---

How It Works

Your repository is parsed into an AST with Tree-sitter, stored as a graph of nodes (functions, classes, imports) and edges (calls, inheritance, test coverage), then queried at review time to compute the minimal set of files your AI assistant needs to read.

Blast-radius analysis

When a file changes, the graph traces every caller, dependent, and test that could be affected. This is the "blast radius" of the change. Your AI reads only these files instead of scanning the whole project.

Incremental updates in < 2 seconds

On every git commit or file save, a hook fires. The graph diffs changed files, finds their dependents via SHA-256 hash checks, and re-parses only what changed. A 2,900-file project re-indexes in under 2 seconds.

The monorepo problem, solved

Large monorepos are where token waste is most painful. The graph cuts through the noise — 27,700+ files excluded from review context, only ~15 files actually read.

19 languages + Jupyter notebooks

Full Tree-sitter grammar support for functions, classes, imports, call sites, inheritance, and test detection in every language. Plus Jupyter/Databricks notebook parsing (.ipynb) with multi-language cell support (Python, R, SQL), and Perl XS files (.xs).

---

Benchmarks

All numbers come from the automated evaluation runner against 6 real open-source repositories (13 commits total). Reproduce with kinrg eval --all. Raw data in evaluate/reports/summary.md.

Token efficiency: 8.2x average reduction (naive vs graph)

The graph replaces reading entire source files with a compact structural context covering blast radius, dependency chains, and test coverage gaps.

Repo	Commits	Avg Naive Tokens	Avg Graph Tokens	Reduction
express	2	693	983	0.7x
fastapi	2	4,944	614	8.1x
flask	2	44,751	4,252	9.1x
gin	3	21,972	1,153	16.4x
httpx	2	12,044	1,728	6.9x
nextjs	2	9,882	1,249	8.0x
Average	13			8.2x

Why express shows <1x: For single-file changes in small packages, the graph context (metadata, edges, review guidance) can exceed the raw file size. The graph approach pays off on multi-file changes where it prunes irrelevant code.

Impact accuracy: 100% recall, 0.54 average F1

The blast-radius analysis never misses an actually impacted file (perfect recall). It over-predicts in some cases, which is a conservative trade-off — better to flag too many files than miss a broken dependency.

Repo	Commits	Avg F1	Avg Precision	Recall
express	2	0.667	0.50	1.0
fastapi	2	0.584	0.42	1.0
flask	2	0.475	0.34	1.0
gin	3	0.429	0.29	1.0
httpx	2	0.762	0.63	1.0
nextjs	2	0.331	0.20	1.0
Average	13	0.54	0.38	1.0

Build performance

Repo	Files	Nodes	Edges	Flow Detection	Search Latency
express	141	1,910	17,553	106ms	0.7ms
fastapi	1,122	6,285	27,117	128ms	1.5ms
flask	83	1,446	7,974	95ms	0.7ms
gin	99	1,286	16,762	111ms	0.5ms
httpx	60	1,253	7,896	96ms	0.4ms

Limitations and known weaknesses

• Small single-file changes: Graph context can exceed naive file reads for trivial edits (see express results above). The overhead is the structural metadata that enables multi-file analysis.
• Search quality (MRR 0.35): Keyword search finds the right result in the top-4 for most queries, but ranking needs improvement. Express queries return 0 hits due to module-pattern naming.
• Flow detection (33% recall): Only reliably detects entry points in Python repos (fastapi, httpx) where framework patterns are recognized. JavaScript and Go flow detection needs work.
• Precision vs recall trade-off: Impact analysis is deliberately conservative. It flags files that might be affected, which means some false positives in large dependency graphs.

---

Features

Feature	Details
Incremental updates	Re-parses only changed files. Subsequent updates complete in under 2 seconds.
19 languages + notebooks	Python, TypeScript/TSX, JavaScript, Vue, Go, Rust, Java, Scala, C#, Ruby, Kotlin, Swift, PHP, Solidity, C/C++, Dart, R, Perl, Lua, Jupyter/Databricks (.ipynb)
Blast-radius analysis	Shows exactly which functions, classes, and files are affected by any change
Auto-update hooks	Graph updates on every file edit and git commit without manual intervention
Semantic search	Optional vector embeddings via sentence-transformers, Google Gemini, or MiniMax
Interactive visualisation	D3.js force-directed graph with edge-type toggles and search
Local storage	SQLite file in .kinrg/. No external database, no cloud dependency.
Watch mode	Continuous graph updates as you work
Execution flows	Trace call chains from entry points, sorted by criticality
Community detection	Cluster related code via Leiden algorithm or file grouping
Architecture overview	Auto-generated architecture map with coupling warnings
Risk-scored reviews	detect_changes maps diffs to affected functions, flows, and test gaps
Refactoring tools	Rename preview, dead code detection, community-driven suggestions
Wiki generation	Auto-generate markdown wiki from community structure
Multi-repo registry	Register multiple repos, search across all of them
MCP prompts	5 workflow templates: review, architecture, debug, onboard, pre-merge
Database Schema Awareness	Parses SQL, Prisma, Django, SQLAlchemy, and TypeORM into standard GraphDB Entities
Full-text search	FTS5-powered hybrid search combining keyword and vector similarity

---

Usage

Slash commands

Command	Description
/kinrg:build-graph	Build or rebuild the code graph
/kinrg:review-delta	Review changes since last commit
/kinrg:review-pr	Full PR review with blast-radius analysis

CLI reference

kinrg install          # Auto-detect and configure all platforms
kinrg install --platform <name>  # Target a specific platform
kinrg build            # Parse entire codebase
kinrg update           # Incremental update (changed files only)
kinrg status           # Graph statistics
kinrg watch            # Auto-update on file changes
kinrg visualize        # Generate interactive HTML graph
kinrg wiki             # Generate markdown wiki from communities
kinrg detect-changes   # Risk-scored change impact analysis
kinrg register <path>  # Register repo in multi-repo registry
kinrg unregister <id>  # Remove repo from registry
kinrg repos            # List registered repositories
kinrg eval             # Run evaluation benchmarks
kinrg serve            # Start MCP server

24 MCP tools

Your AI assistant uses these automatically once the graph is built.

Tool	Description
build_or_update_graph_tool	Build or incrementally update the graph
get_impact_radius_tool	Blast radius of changed files
get_review_context_tool	Token-optimised review context with structural summary
query_graph_tool	Callers, callees, tests, imports, inheritance queries
semantic_search_nodes_tool	Search code entities by name or meaning
embed_graph_tool	Compute vector embeddings for semantic search
list_graph_stats_tool	Graph size and health
get_docs_section_tool	Retrieve documentation sections
find_large_functions_tool	Find functions/classes exceeding a line-count threshold
list_flows_tool	List execution flows sorted by criticality
get_flow_tool	Get details of a single execution flow
get_affected_flows_tool	Find flows affected by changed files
list_communities_tool	List detected code communities
get_community_tool	Get details of a single community
get_architecture_overview_tool	Architecture overview from community structure
detect_changes_tool	Risk-scored change impact analysis for code review
refactor_tool	Rename preview, dead code detection, suggestions
apply_refactor_tool	Apply a previously previewed refactoring
generate_wiki_tool	Generate markdown wiki from communities
get_wiki_page_tool	Retrieve a specific wiki page
list_repos_tool	List registered repositories
cross_repo_search_tool	Search across all registered repositories
list_tables_tool	List all database tables found in the codebase
get_table_tool	Details of a table including columns, FKs, and querying Code

MCP Prompts (5 workflow templates): review_changes, architecture_map, debug_issue, onboard_developer, pre_merge_check

Configuration

To exclude paths from indexing, create a .kinrgignore file in your repository root:

generated/**
*.generated.ts
vendor/**
node_modules/**

Note: in git repos, only tracked files are indexed (git ls-files), so gitignored files are skipped automatically. Use .kinrgignore to exclude tracked files or when git isn't available.

Optional dependency groups:

pip install kinrg[embeddings]          # Local vector embeddings (sentence-transformers)
pip install kinrg[google-embeddings]   # Google Gemini embeddings
pip install kinrg[communities]         # Community detection (igraph)
pip install kinrg[eval]                # Evaluation benchmarks (matplotlib)
pip install kinrg[wiki]                # Wiki generation with LLM summaries (ollama)
pip install kinrg[all]                 # All optional dependencies

---

Contributing

git clone https://github.com/kindy/kinrg.git
cd kinrg
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest

Adding a new language

Edit kinrg/parser.py and add your extension to EXTENSION_TO_LANGUAGE along with node type mappings in _CLASS_TYPES, _FUNCTION_TYPES, _IMPORT_TYPES, and _CALL_TYPES. Include a test fixture and open a PR.

Licence

MIT. See LICENSE.

kinrg.com

pip install kinrg && kinrg install
_{Works with Codex, Claude Code, Cursor, Windsurf, Zed, Continue, OpenCode, and Antigravity}