<h1 align="center">Kodegraf</h1>
<p align="center">
<strong>Structural code intelligence for AI coding assistants. Written in Rust.</strong>
</p>
<p align="center">
<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="#"><img src="https://img.shields.io/badge/version-0.1.0-purple.svg?style=flat-square" alt="v0.1.0"></a>
</p>
---
AI coding tools re-read your entire codebase on every task. Kodegraf fixes that. It builds a structural knowledge graph of your code with [Tree-sitter](https://tree-sitter.github.io/tree-sitter/), validates AI-written code at write-time (DiffGuard), and exposes intelligence via [MCP](https://modelcontextprotocol.io/) so your AI assistant reads only what matters.
## Quick Start
### Install (pick one)
```bash
# Option 1: One-line installer (downloads pre-built binary)
# Option 2: From crates.io
cargo install kodegraf-cli kodegraf-mcp
# Option 3: From source
git clone https://github.com/DeRaowl/Kodegraf.git && cd Kodegraf
cargo install --path crates/kodegraf-cli
cargo install --path crates/kodegraf-mcp
```
### Set up in your project
```bash
cd your-project
kodegraf install
```
That's it. Open Claude Code — Kodegraf is ready. No manual `build` needed.
`install` auto-detects your AI coding tools, builds the knowledge graph, writes MCP config, injects CLAUDE.md instructions, configures hooks, and creates workflow skills. Restart your editor after installing.
## How It Works
```
Your codebase
↓
kodegraf install Auto-detect, build graph, configure everything
↓
Claude Code opens SessionStart hook → graph stats + "Use Kodegraf tools"
↓
User asks a question Claude calls kodegraf_find instead of Grep
↓
Claude writes code PostToolUse hook → kodegraf update --fast (0.1s)
↓
Claude validates kodegraf_check catches hallucinated imports, wrong signatures
```
### Token Reduction
Instead of Claude reading entire files, Kodegraf returns only the structural context — function signatures, import paths, dependency edges. On a 37,000-file monorepo:
| Search latency | ~500ms (grep) | **23ms** (graph) |
| Context per query | ~4,000 tokens (full file) | ~200 tokens (signatures) |
| Build time | N/A | **1:49** for 37K files |
| Incremental update | N/A | **191ms** |
### DiffGuard: Real-Time Validation
Every time Claude writes or edits a file, Kodegraf validates it against the graph:
- **Import exists?** Does the import path resolve to a real file?
- **Function exists?** Does the called function actually exist?
- **Signature matches?** Does the function call have the right number of parameters?
- **Enum value valid?** Is this enum value defined in the source?
Catches AI hallucinations before they reach your PR.
### Self-Improving Loop
Kodegraf records every DiffGuard failure as a signal. Over time, it detects patterns ("Claude keeps inventing `User.authenticate()` — the correct function is `authenticate()`") and generates targeted rules. Each session makes the next one better.
## Architecture
```
┌─────────────────────────────────────────────────────┐
│ kodegraf-cli │
│ clap subcommands: init, build, update, find, deps, │
│ dependents, impact, check, install, eval, serve │
└────────────────────────┬────────────────────────────┘
│
┌────────────────────────▼────────────────────────────┐
│ kodegraf-core │
│ ┌─────────┐ ┌──────────┐ ┌──────────┐ │
│ │ parser │ │ graph │ │ signals │ │
│ │ tree- │→│ SQLite │→│ pattern │ │
│ │ sitter │ │ WAL+FTS5│ │ detect │ │
│ │ 11 langs │ │ BFS/CTE │ │ rules │ │
│ └─────────┘ └──────────┘ └──────────┘ │
└────────────────────────┬────────────────────────────┘
│
┌────────────────────────▼────────────────────────────┐
│ kodegraf-checks │
│ 12 check types: import-exists, fn-exists, │
│ fn-signature, enum-value, type-field, boundary... │
└─────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────┐
│ kodegraf-mcp │
│ rmcp SDK → 10 MCP tools → Claude Code / Cursor │
└─────────────────────────────────────────────────────┘
```
### Crate Structure
| `kodegraf-core` | Graph store, tree-sitter parser, config, signals, walker |
| `kodegraf-cli` | CLI binary with all subcommands |
| `kodegraf-mcp` | MCP server binary (rmcp SDK, 10 tools) |
| `kodegraf-checks` | DiffGuard: 12 validation check types |
## MCP Tools
| `kodegraf_find` | Grep/Glob | Find functions, classes, types by name |
| `kodegraf_search` | Grep | Full-text search across all symbols |
| `kodegraf_deps` | Read | Show what a file imports |
| `kodegraf_dependents` | Grep | Show what imports a file |
| `kodegraf_impact` | Manual tracing | Compute blast radius of changes |
| `kodegraf_check` | CI/build | Validate a file against the graph |
| `kodegraf_exports` | Read | List a file's exported symbols |
| `kodegraf_enum_values` | Read | Get valid enum values |
| `kodegraf_build` | Manual | Build or update the graph |
| `kodegraf_insights` | N/A | Quality metrics and failure patterns |
## Supported Languages
TypeScript, JavaScript, Python, Go, Rust, Java, Ruby, C, C++, C#, Scala.
Additional languages (PHP, Kotlin, Swift, Lua, R, Dart, Perl, Solidity) planned for tree-sitter 0.26 upgrade.
## CLI Reference
```bash
kodegraf init # Initialize in current project
kodegraf build # Full graph build
kodegraf update # Incremental update (changed files only)
kodegraf update --fast # Hook mode: re-parse dirty files, silent
kodegraf install # Auto-configure everything (init + build + MCP + hooks + skills)
kodegraf install --dry-run # Preview what install would do
kodegraf status # Show graph statistics
kodegraf find <query> # Find a symbol
kodegraf deps <file> # Show file dependencies
kodegraf dependents <file> # Show reverse dependencies
kodegraf impact # Blast radius of current changes
kodegraf check <file> # DiffGuard: validate a file
kodegraf insights # Quality metrics
kodegraf eval # Run benchmarks
kodegraf eval --json # Benchmarks as JSON
kodegraf session-greeting # SessionStart hook output
kodegraf serve # Start MCP server
```
## Benchmarks
Run `kodegraf eval` for a full benchmark report. Example on a 37K-file monorepo:
| Search avg latency | **23ms** | 471ms |
| Search P99 latency | **200ms** | 2,314ms |
| DB size | **1.5 GB** | 2.5 GB |
| Nodes extracted | **390K** | 299K |
| Build time (37K files) | **1:49** | 26+ min |
| Incremental update | **191ms** | N/A |
## Development
```bash
# Build
cargo build --workspace
# Test (110 tests)
cargo test --workspace
# Clippy
cargo clippy --workspace
# Install locally
cargo install --path crates/kodegraf-cli
cargo install --path crates/kodegraf-mcp
```
## How It Integrates with Claude Code
`kodegraf install` configures 5 layers of auto-adoption:
1. **MCP Server** (`.mcp.json`): Registers `kodegraf-mcp` as an MCP server
2. **Instructions** (`CLAUDE.md`): "ALWAYS use Kodegraf tools BEFORE Grep/Glob/Read"
3. **Hooks** (`.claude/settings.json`): PostToolUse → `kodegraf update --fast`, SessionStart → `kodegraf session-greeting`
4. **Skills** (`.claude/skills/`): 4 workflow templates (explore, review, debug, refactor)
5. **Auto-build**: Graph built during install, auto-rebuilt on session start if empty
Also supports: Cursor, Windsurf, Zed, Continue.
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.
## Security
See [SECURITY.md](SECURITY.md) for reporting vulnerabilities.
## License
MIT — see [LICENSE](LICENSE).