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>

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

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

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.

Company ROI vs grep and Graphify

For engineering managers choosing a team-wide stack: LeanKG vs Graphify — Company ROI Brief (token/tool-call floors, multi-repo Docker TCO, mega-graph safety, ops/traceability). The primary adoption lever is always-on graph-first install (curl …/install.sh | bash -s -- cursor or claude) so agents query the graph before grep.

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
• Procedural ontology auto-update — edit ontology/workflows.yaml while serving; watcher re-syncs so kg_trace_workflow returns corrected steps without restart
• 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) — explorer shell adapted from GitNexus gitnexus-web (Force / Tree / Circles, filters, search, code panel); data plane is LeanKG /api/* (ui-v2/ + leankg serve)

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

Screenshots

UI v2 uses the GitNexus web exploring shell (layout modes, 3-pane chrome, Sigma) with LeanKG’s REST graph API.

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 · Shell provenance: GitNexus

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 code edges fresh; ontology YAML watch keeps procedural workflows aligned.

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

MCP & Agents

curl -fsSL https://raw.githubusercontent.com/FreePeak/LeanKG/main/scripts/install.sh | bash -s -- cursor
leankg mcp-stdio --watch     # local AI tools
leankg mcp-http --port 9699  # HTTP/SSE for Docker / remote

Prefer-order (discover before connection verbs)

When :9699 health is OK, for fuzzy / NL / “where is X?” questions discover first — do not open with query_graph:

get_overview_context → mcp_status → concept_search → semantic_search → search_code / find_function → then connection verbs → get_context / impact / deps.

Docker MCP: pass container project= (/workspace); override with LEANKG_MCP_PROJECT.

Procedural ontology (auto-update)

While mcp-http / mcp-stdio / leankg serve runs, LeanKG watches ontology/concepts.yaml and ontology/workflows.yaml, debounces (≥1s), and replaces the ontology layer in the served DB so kg_trace_workflow stays fresh without a restart.

Typical agent loop:

1. Wrong workflow steps in YAML → kg_trace_workflow returns them
2. User corrects (rename / add / remove steps) and saves YAML
3. Watcher auto-syncs (YAML is source of truth — old steps disappear, no GID duplicates)
4. Next session query retrieves only the corrected ordered steps

Ontology also refreshes after index, and Docker boot re-syncs when .leankg/ontology_synced is older than either YAML file. Prefer kg_trace_workflow after edits; use ontology_control(action=sync|status) when you need an explicit refresh.

Details: docs/mcp-tools.md · Smoke: docs/reports/ontology-proc-auto-smoke-2026-07-21.md

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):

*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 ontology sync                  # concepts + workflows → DB
leankg ontology trace <workflow>      # ordered procedural steps
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