LeanKG

Local-first code knowledge graph for AI coding agents

Surgical context · fewer tool calls · blast-radius awareness · 100% local

Pre-index your repo. Serve precise subgraphs over MCP to Cursor, Claude Code, OpenCode, and more — no cloud, no external database.

Live Demo → · Docs · Docker Hub

---

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

---

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>

Target	What you get
cursor	Binary + MCP + skill + AGENTS.md + session hook
claude	Binary + MCP + plugin + skill + CLAUDE.md + hooks
opencode	Binary + MCP + plugin + skill + AGENTS.md
gemini / kilo / antigravity	Binary + MCP + skill + agent docs
docker	Hub image + index + embed + MCP HTTP (no Rust)

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

Prefer Cargo or build from source?

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

Teams / Docker (no Rust toolchain)

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 graph-query "what connects auth to the database?"
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

Loading

Without LeanKG	With LeanKG
Grep → open many files → large context	Query the graph → minimal, relevant subgraph
No blast-radius awareness	Impact radius with confidence + severity
Keyword-only search	Keyword + semantic (HNSW) + ontology
Stale mental model of the repo	Index + optional --watch incremental updates

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:

Metric	Result	Floor
Token reduction	−65.0%	≥ 60%
Tool-call reduction	−84.6%	≥ 80%
Speedup	2.50×	≥ 2×
1M SQ8 ANN P95	~0.055 ms	< 50 ms

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

Load test (~100K nodes):

Operation	Throughput
Insert elements	~57k / sec
Insert relationships	~67k / sec
Retrieve elements	~419k / sec
Cache speedup (cold → warm)	345–461×

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 (v2) — GitNexus-inspired explorer: Force / Tree / Circles, filters, search, code panel (ui-v2/ + leankg serve)

Architecture: docs/architecture.md · MCP catalog: docs/mcp-tools.md · UI v2: ui-v2/README.md

---

Screenshots

UI v2 — Force layout (Sigma), filters, and status bar against leankg serve.

 

Tree and Circles layouts on the same subgraph.

Node select opens syntax-highlighted source via /api/file.

 

Header search (/api/search) and Query FAB (/api/query).

Mega-graph skip gate with “Load graph anyway”.

Full set: docs/reports/ui-v2-screenshots-2026-07-20.md · App notes: ui-v2/README.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

Agent	Auto-setup	Notes
Cursor	Yes	Per-project install; session hook; skill using-leankg
Claude Code	Yes	Plugin + full lifecycle hooks
OpenCode	Yes	Plugin + skill
Gemini CLI	Yes	MCP + skill / agent docs
Codex / Antigravity / Kilo	Yes	MCP + skill / agent docs
Docker MCP HTTP	Yes	Shared RocksDB; multi-repo mounts

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

Agent search prefer-order (when :9699 healthy): concept_search → semantic_search → search_code, then exact tools (get_context, impact, deps). Docker MCP: pass container project= (/workspace); override with LEANKG_MCP_PROJECT.

Setup details: docs/agentic-instructions.md · Skill: instructions/using-leankg/SKILL.md · Tool catalog: docs/mcp-tools.md

---

Language Support

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

Family	Languages / formats
Systems	Rust, Go, C / C++*
JVM	Java, Kotlin
Web	TypeScript, JavaScript
Scripting	Python, Ruby*, PHP*
Mobile	Dart, Android XML
Infra	Terraform, CI YAML

*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 graph-query "<question>"
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

Doc	Description
docs/cli-reference.md	All CLI commands
docs/mcp-tools.md	MCP tool reference
docs/agentic-instructions.md	AI tool setup & auto-trigger
docs/architecture.md	System design & data model
docs/web-ui.md	Web UI
docs/benchmark.md	Benchmark methodology
src/embeddings/EMBEDDINGS.md	Embeddings / HNSW internals
INSTRUCTION.md	Memory tuning & ops playbook
docs/roadmap.md	Roadmap
AGENTS.md	Agent / Docker deployment notes

---

Troubleshooting

Issue	Fix
High RAM on macOS	export LEANKG_MMAP_SIZE=134217728 and LEANKG_CACHE_MAX_TOKENS=100000 — see INSTRUCTION.md
database is locked	leankg proc kill (stop web/MCP before re-index)
Embeddings / cold embed	src/embeddings/EMBEDDINGS.md
MCP “not initialized” in Docker	Pass container project= paths (e.g. /workspace), not the host Mac path — see AGENTS.md

---

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