<h1 align="center">Kodegraf</h1>
<p align="center">
<strong>A knowledge graph that makes AI coding assistants actually understand your codebase.</strong>
</p>
<p align="center">
<a href="https://crates.io/crates/kodegraf-cli"><img src="https://img.shields.io/crates/v/kodegraf-cli.svg?style=flat-square" alt="crates.io"></a>
<a href="https://crates.io/crates/kodegraf-cli"><img src="https://img.shields.io/crates/d/kodegraf-cli.svg?style=flat-square" alt="downloads"></a>
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="MIT License"></a>
<a href="https://www.rust-lang.org/"><img src="https://img.shields.io/badge/rust-1.75%2B-orange.svg?style=flat-square" alt="Rust 1.75+"></a>
<a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-compatible-green.svg?style=flat-square" alt="MCP"></a>
<a href="https://github.com/DeRaowl/Kodegraf/releases"><img src="https://img.shields.io/github/v/release/DeRaowl/Kodegraf?style=flat-square" alt="Release"></a>
</p>
---
Your AI assistant doesn't understand your codebase. It reads files, guesses at function names, invents import paths, and hallucinates enum values. Then you fix its mistakes. Then it makes them again next session.
Kodegraf gives it a memory. It parses your code into a queryable graph — every function signature, every import path, every type definition — and serves that knowledge to your AI through [MCP](https://modelcontextprotocol.io/). Your assistant stops guessing. It looks things up.
Built in Rust. Parses 37,000 files in 46 seconds. Searches in 23ms. Zero runtime dependencies.
## Install
```bash
cargo install kodegraf-cli kodegraf-mcp
```
## Set Up (once per project)
```bash
cd your-project
kodegraf install
```
This single command handles everything: parses your codebase, builds the graph, registers the MCP server, and configures your editor. Open Claude Code (or Cursor, Windsurf, Zed) and start working.
## What Happens Next
When your AI assistant needs to find a function, it queries the graph instead of grepping thousands of files. When it writes code, Kodegraf validates the imports, function calls, and enum values against what actually exists. When you switch branches, the graph updates automatically.
```
You: "How is authentication implemented?"
Without Kodegraf: With Kodegraf:
Grep("auth") → 200+ matches kodegraf_find("auth") → 3 results
Read 8 files → 25K tokens Exact signatures, file:line
Guesses import path → wrong Verified import path → correct
3 fix cycles Works first try
```
## 17 Tools
| `kodegraf_find` | Find functions, classes, types by name with signatures |
| `kodegraf_search` | Full-text search across all symbols (FTS5 + porter stemmer) |
| `kodegraf_deps` | What does this file import? |
| `kodegraf_dependents` | What imports this file? |
| `kodegraf_impact` | Blast radius — what breaks if you change this? |
| `kodegraf_check` | Validate code against the graph (DiffGuard) |
| `kodegraf_exports` | List a file's exported symbols |
| `kodegraf_enum_values` | Get valid enum values (never guess) |
| `kodegraf_context` | ~100 token summary with next-step suggestions |
| `kodegraf_query` | Trace callers, callees, imports, tests for any symbol |
| `kodegraf_changes` | Risk-scored git diff with test gap detection |
| `kodegraf_flows` | Execution flows sorted by criticality |
| `kodegraf_affected_flows` | Which user-facing paths are impacted by changes? |
| `kodegraf_large` | Find oversized functions for decomposition |
| `kodegraf_dead_code` | Find unreferenced code |
| `kodegraf_build` | Build or update the graph |
| `kodegraf_insights` | Quality metrics and failure patterns |
## DiffGuard
Every time your AI writes code, Kodegraf checks it against the graph:
- Does the import path resolve to a real file?
- Does the function being called actually exist?
- Does the function signature match (parameter count, types)?
- Is the enum value valid?
Errors are caught before they reach your PR. Failures are recorded, patterns are detected, and prevention rules are generated automatically. The system gets smarter every session.
## Performance
Tested on a production monorepo with 37,000 source files:
| Full build | **46 seconds** |
| Incremental update | **191ms** |
| Search latency (avg) | **23ms** |
| Search latency (P99) | **200ms** |
| Symbols indexed | **390,000** |
| Dependency edges | **2.5 million** |
Parallel parsing with 8 threads. SQLite with WAL mode, FTS5 full-text search, 64MB cache. All queries use prepared statements.
## Languages
TypeScript, JavaScript, Python, Go, Rust, Java, Ruby, C, C++, C#, Scala.
## How It Integrates
`kodegraf install` sets up five layers automatically:
1. **MCP Server** — registers with your AI tool via `.mcp.json`
2. **Instructions** — prepends CLAUDE.md with "use Kodegraf tools first"
3. **Hooks** — auto-updates graph after every file edit (191ms, silent)
4. **Skills** — workflow templates for explore, review, debug, refactor
5. **Auto-build** — graph rebuilt on session start if empty or stale
Works with Claude Code, Cursor, Windsurf, Zed, and Continue.
## CLI
```bash
kodegraf install # Set up everything (one command)
kodegraf build # Full graph build
kodegraf update # Incremental update
kodegraf update --fast # Hook mode (silent, <200ms)
kodegraf find <query> # Find a symbol
kodegraf deps <file> # File dependencies
kodegraf dependents <file> # Reverse dependencies
kodegraf impact # Blast radius of current changes
kodegraf check <file> # Validate a file (DiffGuard)
kodegraf eval # Run benchmarks
kodegraf status # Graph statistics
```
## Architecture
Four Rust crates. Two binaries. One SQLite database.
| [kodegraf-core](https://crates.io/crates/kodegraf-core) | Graph store, tree-sitter parser, FTS5 search, flow detection, signals |
| [kodegraf-checks](https://crates.io/crates/kodegraf-checks) | DiffGuard — 12 validation rules with fuzzy matching |
| [kodegraf-cli](https://crates.io/crates/kodegraf-cli) | CLI binary with all commands |
| [kodegraf-mcp](https://crates.io/crates/kodegraf-mcp) | MCP server (rmcp SDK, 17 tools, stdio transport) |
## Development
```bash
cargo build --workspace # Build
cargo test --workspace # 112 tests
cargo clippy --workspace # Lint
```
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md).
## Security
See [SECURITY.md](SECURITY.md). Kodegraf is local-only — no network calls, no telemetry, no cloud.
## License
MIT