LeanKG

Lightweight Knowledge Graph for AI-Assisted Development

LeanKG is a local-first knowledge graph that gives AI coding tools accurate codebase context. It indexes your code, builds dependency graphs, generates documentation, and exposes an MCP server so tools like Cursor, OpenCode, and Claude Code can query the knowledge graph directly. No cloud services, no external databases -- everything runs on your machine with minimal resources.

graph LR
    subgraph "Without LeanKG"
        A1[AI Tool] -->|Scans entire codebase| B1[10,000+ tokens]
        B1 --> A1
    end

    subgraph "With LeanKG"
        A2[AI Tool] -->|13-42 tokens| C[LeanKG Graph]
        C -->|Targeted subgraph| A2
    end

Without LeanKG: AI scans entire codebase, wasting tokens on irrelevant context (~10,000+ tokens).

With LeanKG: AI queries the knowledge graph for targeted context only (13-42 tokens). 98% token saving for impact analysis.

Install the LeanKG binary, configure MCP, and add agent instructions for your AI coding tool:

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

This installs:

1. LeanKG binary to ~/.local/bin
2. MCP configuration for your AI tool
3. Agent instructions (LeanKG tool usage guidance) to the tool's config directory

Supported targets:

Examples:

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

# Install for Cursor (binary only - see per-project setup below)
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 for Gemini CLI
curl -fsSL https://raw.githubusercontent.com/FreePeak/LeanKG/main/scripts/install.sh | bash -s -- gemini

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

LeanKG for Cursor includes:

• Global MCP server - ~/.cursor/mcp.json adds LeanKG to all projects
• Plugin - ~/.cursor/plugins/leankg/ with:
  • skills/using-leankg/SKILL.md - Mandatory LeanKG-first skill
  • rules/leankg-rule.mdc - Auto-trigger rule for code search
  • agents/leankg-agents.md - Agent instructions
  • commands/leankg-commands.md - Command reference
  • hooks/session-start - Session bootstrap hook
• User skill preservation - Other skills in ~/.cursor/skills/ are NOT removed

LeanKG uses per-project MCP configuration for Cursor. This allows LeanKG to automatically detect and index the project you're working on.

In each project directory, run:

leankg install    # Creates .cursor/mcp.json in the project

This creates .cursor/mcp.json which Cursor automatically detects when you open that project.

Example workflow:

# First time: install LeanKG binary globally
curl -fsSL https://raw.githubusercontent.com/FreePeak/LeanKG/main/scripts/install.sh | bash -s -- cursor

# Then in each project you want to use LeanKG with:
cd /path/to/project
leankg install    # Creates .cursor/mcp.json
# Restart Cursor or click refresh in MCP settings

cargo install leankg
leankg --version

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

Use GitHub Codespaces to try LeanKG in your browser - no installation required!

1. Go to github.com/FreePeak/LeanKG
2. Click "Code" → "Create Codespace"
3. LeanKG auto-installs when the codespace starts
4. In the terminal:

   leankg index ./src
   leankg web

5. Click "Open in Browser" on port 8080

Free tier: 60 hours/month (3 months), then 15 hours/month

Try LeanKG without installing - visit the live demo at https://leankg.onrender.com

To update LeanKG to the latest version, run the same install command:

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

This will replace the existing binary with the latest release while preserving your configuration.

# 1. Initialize LeanKG in your project
leankg init

# 2. Index your codebase
leankg index ./src

# 3. Start the MCP server (for AI tools)
leankg serve

# 4. Start the Web UI (for visualization)
# Open http://localhost:8080 in your browser
leankg web

# 5. Run commands with RTK-style compression
leankg run "cargo test"

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

# 7. Check index status
leankg status

# 8. Watch for changes and auto-index
leankg watch ./src

# 9. View context metrics (token savings)
leankg metrics
leankg metrics --seed  # Seed test data

graph TB
    subgraph "Developer Machine"
        subgraph "LeanKG System"
            direction TB
            CLI["CLI<br/>init, index, serve, watch"]
            
            subgraph "Indexer"
                Parser["Parser<br/>(tree-sitter)"]
                Extractor["Extractor<br/>functions, classes, imports, calls"]
            end
            
            DB[("CozoDB<br/>SQLite")]
            
            subgraph "MCP Server"
                Tools["MCP Tools<br/>search, query, impact, context"]
            end
            
            subgraph "Web UI"
                Graph["Graph Viewer<br/>sigma.js"]
                API["REST API<br/>/api/graph/data"]
            end
        end
        
        AI["AI Tool<br/>(Claude, Cursor, OpenCode)"]
    end
    
    CLI -->|init| DB
    CLI -->|index| Parser
    Parser -->|parse| Extractor
    Extractor -->|store| DB
    CLI -->|serve| MCP
    DB -->|query| Tools
    Tools -->|MCP| AI
    CLI -->|web| API
    API -->|fetch| Graph
    Extractor -->|watch| CLI

graph LR
    subgraph "1. Index Phase"
        A["Source Code<br/>*.rs, *.ts, *.py, *.go, *.java, *.kt, *.tf, *.yml"] --> B["tree-sitter Parser"]
        B --> C["Code Elements<br/>functions, classes, modules"]
        B --> D["Relationships<br/>imports, calls, tested_by"]
        C --> E[("CozoDB")]
        D --> E
    end
    
    subgraph "2. Query Phase"
        E --> F["MCP Tools"]
        F --> G["AI Tool Context<br/>13-42 tokens"]
    end

Key Insight: The graph stores the FULL dependency graph at indexing time. When you query, LeanKG traverses N hops from your target to find all affected elements - no file scanning needed.

See MCP Setup for detailed setup instructions for all supported AI tools.

LeanKG instructs AI coding agents to use LeanKG first for codebase queries.

Add this to your AI tool's instruction file:

## 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`, `get_dependencies`, `get_dependents`, `get_tested_by`, `get_context`, `get_review_context`
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` or `detect_changes` |
| What tests cover Y? | `get_tested_by` |
| How does X work? | `get_context`, `get_review_context` |
| Read file efficiently? | `ctx_read` (with adaptive/full/map/signatures modes) |
| Intelligent routing? | `orchestrate` (cache-graph-compress flow) |

See Agentic Instructions for detailed setup.

All tools use the same MCP config. The install script handles setup automatically:

Manual MCP config (same for all tools):

{
  "mcpServers": {
    "leankg": {
      "command": "leankg",
      "args": ["mcp-stdio", "--watch"]
    }
  }
}

See MCP Setup for per-tool configuration details.

• Token Concise -- Returns 13-42 tokens per query vs 10,000+ tokens for full codebase scan. AI tools get exactly what they need.
• Token Saving -- Up to 98% token reduction for impact analysis queries. Index once, query efficiently forever.
• Code Indexing -- Parse and index Go, TypeScript, Python, Rust, Java, Kotlin, C++, C#, Ruby, and PHP codebases with tree-sitter.
• Dependency Graph -- Build call graphs with IMPORTS, CALLS, TESTED_BY, and REFERENCES edges.
• Impact Radius -- Compute blast radius for any file to see downstream impact with severity classification (WILL BREAK, LIKELY AFFECTED, MAY BE AFFECTED).
• Cluster Detection -- Community detection to identify code clusters and their relationships.
• Business Logic Mapping -- Annotate code elements with business logic, link to user stories and features, trace requirements to code.
• Auto-Indexing -- Watch mode automatically updates the index when files change.
• Context Metrics -- Track token savings, F1 scores, and usage statistics per tool call with full query metadata.
• Auto Documentation -- Generate markdown docs from code structure automatically.
• MCP Server -- Expose the graph via MCP protocol for AI tool integration (stdio transport).
• File Watching -- Watch for changes and incrementally update the index.
• CLI -- Single binary with 30+ commands for indexing, querying, annotating, benchmarking, and serving.
• RTK Compression -- RTK-style compression for CLI output and MCP responses (leankg run, compress_response on all graph tools).
• Orchestrator -- Intelligent query routing with cache-graph-compress flow and adaptive compression modes.
• Traceability -- Show feature-to-code and requirement-to-code traceability chains via trace command.
• Documentation Mapping -- Index docs/ directory, map doc references to code elements, generate get_doc_for_file chains.
• Graph Viewer -- Visualize knowledge graph using standalone web UI with sigma.js.
• REST API -- Start a REST API server with authentication (leankg api-serve --port 8080 --auth).
• Global Registry -- Manage multiple repositories from a single global registry (leankg register, leankg list).
• Benchmark -- Compare LeanKG context quality against OpenCode, Gemini, and Kilo CLI tools.
• Compression Modes -- File reading with adaptive modes: adaptive, full, map, signatures, diff, aggressive, entropy, lines.
• Change Detection -- Pre-commit risk analysis with severity levels (critical/high/medium/low) via detect_changes tool.
• Multi-Language -- Also supports Terraform (.tf), CI/CD YAML (GitHub workflows, GitLab CI, Azure Pipelines), and Markdown docs.
• Test Detection -- Auto-detects test files across all languages and creates tested_by relationships.

LeanKG provides concise context (targeted subgraph, not full scan) and saves tokens over baseline.

Key Findings:

• LeanKG wins on F1 context quality in 2/7 tests (navigation, impact analysis)
• Token overhead: +41,048 tokens across all tests (pending deduplication fix)
• Context deduplication optimizations pending (see AB Testing Results)

Historical (2026-03-25): 98.4% token savings for impact analysis on Go example

See AB Testing Results for detailed analysis and benchmark/README.md for test methodology.

Start the web UI with leankg web and open http://localhost:8080.

The graph viewer provides an interactive visualization of your codebase's dependency graph. Filter by element type, zoom, pan, and click nodes for details.

See Web UI for detailed documentation.

LeanKG watches your codebase and automatically keeps the knowledge graph up-to-date. When you modify, create, or delete files, LeanKG incrementally updates the index.

# Watch mode - auto-index on file changes
leankg watch ./src

# Or use the serve command with auto-index enabled
leankg web --watch ./src

See CLI Reference for detailed commands.

Track token savings and usage statistics to understand how LeanKG improves your AI tool's context efficiency.

# View metrics summary
leankg metrics

# View with JSON output
leankg metrics --json

# Filter by time period
leankg metrics --since 7d

# Filter by tool name
leankg metrics --tool search_code

# Seed test data for demo
leankg metrics --seed

# Reset all metrics
leankg metrics --reset

# Cleanup old metrics (retention: 30 days default)
leankg metrics --cleanup --retention 60

Note: Entries with negative savings (where LeanKG outputs more tokens than baseline) are automatically filtered from the display. This ensures metrics only show tools that actually saved tokens.

=== LeanKG Context Metrics ===

Total Savings: 64,160 tokens across 7 calls
Average Savings: 99.4%
Retention: 30 days

By Tool:
  search_code:        2 calls,  avg 100% saved, 25,903 tokens saved
  get_impact_radius:  1 calls,  avg 99% saved, 24,820 tokens saved
  get_context:        1 calls,  avg 100% saved, 7,965 tokens saved
  find_function:      1 calls,  avg 100% saved, 5,972 tokens saved

Average calculation: Only entries with positive savings_percent contribute to the average. Negative entries (where LeanKG outputs more tokens than baseline) are excluded from both the total count and the percentage calculation.

For the complete CLI reference, see CLI Reference.

See MCP Tools for the complete list of available tools.

See Roadmap for detailed feature planning and implementation status.

• Rust 1.70+
• macOS or Linux

See Tech Stack for architecture, tech stack details, and project structure.

MIT