kodegraf-cli 0.1.2

Structural code intelligence for AI coding assistants — CLI
kodegraf-cli-0.1.2 is not a library.

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

# Step 1: Install the binaries (once, ever)
cargo install --git https://github.com/DeRaowl/Kodegraf kodegraf-cli
cargo install --git https://github.com/DeRaowl/Kodegraf kodegraf-mcp

# Step 2: Set up in your project (once per repo)
cd your-project
kodegraf install

# Step 3: Open your AI coding tool
claude    # or cursor, windsurf, zed

Both steps are required. Step 1 puts the binaries on your machine. Step 2 builds the knowledge graph and configures your AI tool to use it. Without Step 2, your AI tool won't know Kodegraf exists.

kodegraf install does everything automatically: builds the 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:

Metric Without Kodegraf With Kodegraf
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

Crate Purpose
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

Tool Use instead of What it does
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

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:

Metric Value
Search avg latency 23ms
Search P99 latency 200ms
Build time (37K files) 1:49
Incremental update 191ms
Nodes extracted 390K
DB size 1.5 GB
Search hit rate 100%
Mean Reciprocal Rank 0.90

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.

Crates

Crate crates.io Description
kodegraf-cli CLI binary (kodegraf)
kodegraf-mcp MCP server binary (kodegraf-mcp)
kodegraf-core Core library (graph, parser, signals)
kodegraf-checks DiffGuard validation engine

Contributing

See CONTRIBUTING.md for development guidelines.

Security

See SECURITY.md for reporting vulnerabilities.

License

MIT — see LICENSE.