kodegraf-cli 0.1.0

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, validates AI-written code at write-time (DiffGuard), and exposes intelligence via MCP so your AI assistant reads only what matters.

Quick Start

Install (pick one)

# Option 1: One-line installer (downloads pre-built binary)
curl -fsSL https://raw.githubusercontent.com/DeRaowl/Kodegraf/main/install.sh | bash

# 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

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:

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

MCP Tools

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

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:

Development

# 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 for development guidelines.

Security

See SECURITY.md for reporting vulnerabilities.

License

MIT — see LICENSE.