LeanKG Docs

What is LeanKG?

LeanKG is a local-first knowledge graph that gives AI coding tools accurate codebase context. It indexes your code, builds dependency graphs, and exposes an MCP server so tools like Claude, Cursor, and OpenCode can query the knowledge graph directly.

Core Benefits

• Token Concise: Returns 13-42 tokens per query vs 10,000+ tokens for full codebase scan
• Token Saving: Up to 98% token reduction for impact analysis queries
• Local-First: Everything runs on your machine with CozoDB SQLite storage
• Auto-Indexing: Watches for changes and incrementally updates the index

One-Line Install (Recommended)

curl -fsSL https://raw.githubusercontent.com/FreePeak/LeanKG/main/scripts/install.sh | bash -s -- <target>

Supported Targets

• opencode - OpenCode AI
• cursor - Cursor AI
• claude - Claude Code/Desktop
• gemini - Gemini CLI
• kilo - Kilo Code
• antigravity - Google Antigravity

Examples

# Install for OpenCode
curl -fsSL https://raw.githubusercontent.com/FreePeak/LeanKG/main/scripts/install.sh | bash -s -- opencode

# Install for Cursor
curl -fsSL https://raw.githubusercontent.com/FreePeak/LeanKG/main/scripts/install.sh | bash -s -- cursor

# Install for Claude Code
curl -fsSL https://raw.githubusercontent.com/FreePeak/LeanKG/main/scripts/install.sh | bash -s -- claude

Install via Cargo

cargo install leankg
leankg --version

Build from Source

git clone https://github.com/FreePeak/LeanKG.git
cd LeanKG
cargo build --release

Step 1: Initialize

Creates .leankg/ directory and leankg.yaml configuration.

# Initialize LeanKG in your project directory
leankg init

Step 2: Index Your Codebase

Parses code with tree-sitter, extracts functions, classes, imports, and call relationships.

# Index all source files
leankg index ./src

# With language filter
leankg index ./src --lang go,ts,py,rs

# Incremental index (only changed files)
leankg index --incremental

Step 3: Start MCP Server

Exposes MCP tools for AI tools to query your knowledge graph.

# Start MCP server for AI tools
leankg serve

# Or with stdio transport (for local AI tools)
leankg mcp-stdio --watch

Step 4: Start Web UI (Optional)

Visualize your codebase's dependency graph in real-time.

# Start web UI for graph visualization
leankg web
# Open http://localhost:8080

Step 5: Check Status

Shows database statistics, indexed files count, and last update time.

# View index statistics
leankg status

OpenCode AI

// Add to ~/.config/opencode/opencode.json
{
  "mcp": {
    "leankg": {
      "type": "local",
      "command": ["leankg", "mcp-stdio", "--watch"],
      "enabled": true
    }
  }
}

Cursor AI

// Add to ~/.cursor/mcp.json
{
  "mcpServers": {
    "leankg": {
      "command": "leankg",
      "args": ["mcp-stdio", "--watch"]
    }
  }
}

Claude Code / Desktop

// Add to ~/.config/claude/settings.json
{
  "mcpServers": {
    "leankg": {
      "command": "leankg",
      "args": ["mcp-stdio", "--watch"]
    }
  }
}

Gemini CLI

// Add to ~/.config/gemini-cli/mcp.json
{
  "mcpServers": {
    "leankg": {
      "command": "leankg",
      "args": ["mcp-stdio", "--watch"]
    }
  }
}

Kilo Code

// Add to ~/.config/kilo/kilo.json
{
  "mcp": {
    "leankg": {
      "type": "local",
      "command": ["leankg", "mcp-stdio", "--watch"],
      "enabled": true
    }
  }
}

Auto-Initialization

When the MCP server starts without an existing LeanKG project, it automatically initializes and indexes the current directory. Provides a 'plug and play' experience for AI tools.

Auto-Indexing

When the MCP server starts with an existing LeanKG project, it checks if the index is stale. If stale, it automatically runs incremental indexing to ensure AI tools have up-to-date context.

Core Commands

• leankg init - Initialize LeanKG in the current directory
• leankg index [path] - Index source files at the given path
• leankg serve - Start the MCP server (WebSocket)
• leankg mcp-stdio - Start MCP server with stdio transport
• leankg status - Show index statistics and status
• leankg watch - Start file watcher for auto-indexing

Indexing Options

# Index with language filter
leankg index ./src --lang go,ts,py,rs,java,kotlin

# Exclude patterns
leankg index ./src --exclude vendor,node_modules,dist

# Incremental index (git-based, only changed files)
leankg index --incremental

Analysis Commands

# Compute blast radius for a file
leankg impact src/main.rs --depth 3

# Find oversized functions
leankg quality --min-lines 50

# Query the knowledge graph
leankg query "authentication" --kind name

Documentation & Traceability

# Generate documentation from the graph
leankg generate

# Show documentation structure
leankg docs --tree

# Show docs for a file
leankg docs --for src/auth.rs

# Show feature-to-code traceability
leankg trace --feature AUTH-001

Core Tools

• mcp_init - Initialize LeanKG project
• mcp_index - Index codebase (path, incremental, lang, exclude options)
• mcp_install - Create .mcp.json for MCP client configuration
• mcp_status - Show index statistics and status
• mcp_impact - Calculate blast radius for a file

Query Tools

• query_file - Find file by name or pattern
• find_function - Locate function definition by name
• search_code - Search code elements by name/type
• get_call_graph - Get function call chain (full depth)

Dependency Analysis

• get_dependencies - Get file dependencies (direct imports)
• get_dependents - Get files depending on target
• get_impact_radius - Get all files affected by change within N hops
• get_review_context - Generate focused subgraph + structured review prompt

Context Tools

• get_context - Get AI context for file (minimal, token-optimized)
• get_tested_by - Get test coverage for a function/file
• find_large_functions - Find oversized functions by line count

Documentation Tools

• generate_doc - Generate documentation for file
• get_doc_for_file - Get documentation files referencing a code element
• get_files_for_doc - Get code elements referenced in a documentation file
• get_doc_structure - Get documentation directory structure

Traceability Tools

• get_traceability - Get full traceability chain for a code element
• search_by_requirement - Find code elements related to a requirement

Full Support

• Go (.go) - functions, structs, interfaces, imports, calls
• TypeScript (.ts, .tsx) - functions, classes, imports, calls
• JavaScript (.js, .jsx) - functions, classes, imports, calls
• Python (.py) - functions, classes, imports, calls
• Rust (.rs) - functions, structs, traits, imports, calls
• Java (.java) - classes, interfaces, methods, constructors, enums, imports, calls
• Kotlin (.kt, .kts) - classes, objects, companion objects, functions, constructors, imports, calls
• Terraform (.tf) - resources, variables, outputs, modules
• YAML (.yaml, .yml) - CI/CD pipelines, configurations
• Markdown (.md) - documentation sections, code references

Node Types

• function - Code functions (e.g., src/auth.rs::validate_token)
• class - Classes and structs (e.g., src/db/models.rs::User)
• module - Files/modules (e.g., src/db/models.rs)
• document - Documentation files (e.g., docs/architecture.md)
• doc_section - Doc headings (e.g., docs/api.md::Usage)

Relationship Types

• calls (A → B) - Function A calls function B
• imports (A → B) - Module A imports module B
• contains (doc → section) - Document contains section
• tested_by (A → B) - Code A is tested by test B
• documented_by (A → B) - Code A is documented by doc B

How It Works

LeanKG provides agentic instructions that tell AI coding tools to use LeanKG FIRST for codebase queries before scanning the entire codebase.

Core Rule for AI Tools

## MANDATORY: Use LeanKG First
Before ANY codebase search/navigation, use LeanKG tools:
1. mcp_status - check if ready
2. Use tool: search_code, find_function, query_file, get_impact_radius
3. Only fallback to grep/read if LeanKG fails

| Task              | Use |
|-------------------|-----|
| Where is X?       | search_code or find_function |
| What breaks if I change Y? | get_impact_radius |
| What tests cover Y? | get_tested_by |
| How does X work?  | get_context |

Supported AI Tools

• Claude Code - MCP integration with CLAUDE.md agent instructions
• OpenCode - MCP integration with AGENTS.md agent instructions
• Cursor - MCP integration with AGENTS.md agent instructions
• KiloCode - MCP integration with AGENTS.md agent instructions
• Codex - MCP integration with AGENTS.md agent instructions
• Gemini CLI - MCP integration with GEMINI.md agent instructions
• Google Antigravity - MCP integration with GEMINI.md agent instructions

A/B Test Results (2026-04-21)

• F1 context quality wins in navigation queries
• F1 context quality wins in impact analysis queries
• Context correctness: F1 0.31-0.46 on complex queries

Load Test Results (100K nodes)

• 57,618 elements/sec insert throughput
• 67,067 relationships/sec insert
• 418,718 elements/sec retrieve throughput
• 345-461x cache speedup (cold to warm)

Benchmark Notes

Token savings vary by task complexity. Complex impact/debugging queries may timeout. LeanKG excels at targeted subgraph retrieval vs full codebase scanning.

LeanKG Not Initialized

If the MCP server reports 'LeanKG not initialized', manually run leankg init in your project directory, then restart the AI tool.

Index Out of Date

Run leankg index --incremental to update the index with the latest changes, or leankg watch to enable automatic background indexing.

MCP Connection Issues

# Check if LeanKG is running
leankg status

# Restart MCP server
leankg mcp-stdio --watch

Need Help?

Visit the GitHub repository for issues, discussions, and support.