LeanKG

Contents

• Get Started

• Why LeanKG?

• Measured Results

• Key Features

• Screenshots

• How It Works

• MCP & Agents

• Language Support

• CLI Quick Reference

• Documentation

• Troubleshooting

• Contributing

• License

• Star History

Related MCP server: CodeXRay

Get Started

1. Install the CLI

One command — binary, MCP wiring, and agent docs for your tool of choice:

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

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

cargo install leankg
# or
git clone https://github.com/FreePeak/LeanKG.git && cd LeanKG && cargo build --release

curl -fsSL https://raw.githubusercontent.com/FreePeak/LeanKG/main/scripts/docker-up.sh | bash
curl http://localhost:9699/health

Point your MCP client at http://localhost:9699/mcp. Multi-project RocksDB mounts: AGENTS.md.

Published Hub tags currently target linux/arm64. On linux/amd64, build with docker compose -f docker-compose.rocksdb.yml up --build.

2. Wire up your agent(s)

Installing the binary alone does not connect your agent. Run setup (or use an install target above) so MCP is registered:

leankg setup

This configures Cursor, Claude Code, OpenCode, Gemini, and other supported clients with LeanKG’s MCP server, skills, and hooks where available.

3. Index each project

cd your-project
leankg init
leankg index ./src
leankg status

Optional: enable watch mode so the graph stays fresh while you and your agent edit code:

leankg mcp-stdio --watch

4. Ask better questions

leankg impact src/main.rs --depth 3
leankg path "Handler" "Repository"
leankg explain "APIRouter"
leankg web    # UI at http://localhost:8080

Upgrade anytime:

leankg update

Why LeanKG?

When an AI agent needs to understand code, it usually discovers structure the slow way: grep, glob, and Read — one file at a time — rebuilding call paths and dependencies by hand. That is a pile of tool calls and round-trips before the real work starts.

LeanKG hands the agent the exact subgraph it needs. It indexes symbols, edges, tests, docs, and (optionally) embeddings into a local knowledge graph, then exposes them over MCP. Instead of crawling the tree, the agent asks one question and gets back callers, dependents, blast radius, and targeted source — surgical context, not a file-by-file search.

graph LR
    A[AI Agent] -->|intent| B[LeanKG MCP]
    B --> C[Graph + Embeddings]
    C -->|targeted context| A

On cost: LeanKG’s win on every codebase is precision and speed — fewer tool calls, faster answers. Token savings are real and scale-dependent: modest on small repos, material on large monorepos multiplied by team-wide agent usage.

Measured Results

Vector-engine A/B gate (100 tasks, synthetic agent workload vs grep/cat-style baseline) — see docs/benchmarks/vector_engine_gate_results.json:

Unified agent A/B (19 cases vs grep baseline): ~30% input token savings, ~3× tokens/result efficiency.

Load test (~100K nodes):

cargo build --release
target/release/leankg benchmark-unified --project .
cargo bench --bench vector_engine_ab

Full methodology: docs/benchmark.md

Key Features

• MCP-native — 85+ tools for search, impact, call graphs, ontology, architecture, and team knowledge

• Impact radius — blast radius before you change code, with confidence and severity

• Dependency graph — imports, calls, tested_by, http_calls, service_calls, tunnels, and more

• Semantic search — CozoDB HNSW over dense embeddings (--features embeddings; included in Docker)

• Community detection — Leiden clusters with per-cluster skill context

• Local-first storage — SQLite by default; RocksDB for multi-project / team deploy

• Token-aware payloads — targeted subgraphs + TOON responses (~40% smaller MCP payloads)

• Team knowledge — incidents, env conflicts, service topology, Obsidian vault sync

• Graph export — Mermaid, DOT, HTML, SVG, GraphML, Neo4j, portable snapshots

• Web UI — force-directed graph, WebGL rendering, community clustering, linked source view

Architecture: docs/architecture.md · MCP catalog: docs/mcp-tools.md

Screenshots

UI guide: docs/web-ui.md · Live demo: https://leankg.onrender.com

How It Works

1. Extract — tree-sitter (and language-specific extractors) turn source into CodeElement nodes and typed relationships.

2. Store — CozoDB over SQLite (local) or RocksDB (multi-project / Docker) holds the graph + optional HNSW vectors.

3. Serve — MCP stdio (editor agents) or HTTP/SSE (Docker / remote) answers tools like get_impact_radius, search_code, semantic_search, get_architecture.

4. Refresh — --watch and incremental index keep the graph aligned with the working tree.

Repo ──► Indexer ──► Knowledge Graph ──► MCP Tools ──► AI Agent
              │              │
              └─ embeddings ─┘ (optional)

MCP & Agents

leankg setup                 # configure MCP + hooks
leankg mcp-stdio --watch     # local AI tools
leankg mcp-http --port 9699  # HTTP/SSE for Docker / remote

Setup details: docs/agentic-instructions.md

Language Support

Structural extraction and cross-file edges into one graph (no per-language product setup):

*Depth varies by extractor maturity — see the PRD / roadmap for parity status.

CLI Quick Reference

leankg init
leankg index ./src
leankg status
leankg impact <file> --depth 3
leankg path <from> <to>
leankg explain <symbol>
leankg detect-clusters
leankg embed --init && leankg embed   # needs --features embeddings
leankg web
leankg mcp-stdio --watch
leankg mcp-http --port 9699
leankg update

Full CLI: docs/cli-reference.md

Documentation

Troubleshooting

Requirements

• Rust 1.75+ (only when building from source)

• macOS or Linux

• Docker optional (recommended for teams / multi-repo)

Contributing

Issues and PRs are welcome. For larger changes, open an issue first so we can align on design.

1. Fork and create a feature branch (prefer a git worktree for isolation)

2. Update docs when behavior changes (docs/prd.md / task tracker as needed)

3. cargo build --release && cargo test

4. Open a PR with a clear summary and test plan

License

Apache License 2.0

Star History