LeanKG

LeanKG

Enterprise-ready code knowledge graph for AI coding agents
Multi-repo · env governance · incidents & services · req↔code · −65% tokens / −85% tool calls

Live Demo · Docs ·

---

Installation

Prerequisites

None — sqlite is the default storage engine. No Postgres, no Docker.

Postgres remains available as an explicit opt-in (LEANKG_DB_ENGINE=postgres + LEANKG_PG_URL) for server-scale deployments, but nothing in the default flow touches it.

One-liners

# Agent — binary + MCP wiring (cursor | claude | opencode | gemini | kilo | antigravity | update)
curl -fsSL https://raw.githubusercontent.com/FreePeak/LeanKG/main/scripts/install.sh | bash -s -- cursor

From source

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

---

Get Started

# 1. Per project: init -> migrate -> index (sqlite default — zero config)
cd your-project
leankg init && leankg migrate && leankg index ./src

# 2a. Wire up an AI client — one command (also: cursor | codex | gemini)
leankg connect claude-code           # add --remote http://host:9699 to reuse a shared server

# 2b. ...or serve MCP over HTTP yourself
leankg mcp-http --port 9699          # GET /health returns 200 when ready

Self-check any deployment: leankg doctor --deep — index freshness, migrations, embedding coverage, orphan edges, duplicate names (exit 0 pass / 1 warn / 2 fail).

Measured timings (scripts/quickstart_smoke.sh, run weekly in CI): full e2e smoke 88 s vs a 300 s budget; indexing a small repo takes well under 2 minutes.

MCP HTTP: pass the project checkout directory as project=.

Server-side setup pipeline (clone -> index -> embed)

leankg setup with no flags keeps the legacy client-side behavior (register MCP + hooks). Pass pipeline flags to instead clone a list of repos and index each one server-side:

# Status: print the resolved repo list without running anything
LEANKG_REPOS="github.com/org/repo-a,github.com/org/repo-b" leankg setup --status

# Clone + index + embed each repo under LEANKG_CLONE_ROOT (default: cwd)
LEANKG_REPOS="github.com/org/repo-a,github.com/org/repo-b" \
  LEANKG_GIT_REF=main \
  LEANKG_CLONE_ROOT=/srv/repos \
  leankg setup --clone --index --embed

Repo sources:

• LEANKG_REPOS — comma-separated host/namespace paths to clone.
• LEANKG_PROJECT_DIRS — comma-separated dirs already mounted on disk (skips clone; falls back to indexing what exists when no git token is set).

Env knobs: LEANKG_GIT_HOST (default github.com), LEANKG_GIT_REF (default main), LEANKG_CLONE_ROOT / CLONE_ROOT, LEANKG_ENV (default local), git token via GITLAB_TOKEN / GIT_TOKEN / GITHUB_TOKEN. Each cloned repo gets a minimal .leankg/leankg.yaml, then leankg index and leankg embed --wait run inside it. A setup.done marker prevents re-runs.

Set LEANKG_SETUP=1 on leankg mcp-http to run the same pipeline once after the server binds (spawned as a background task; the server stays healthy).

Web UI

UI talks REST (:8080), not MCP (:9699). Start the API, then the Vite app in ui-v2/:

# Terminal A — REST API (+ embedded UI if assets are in src/embed/)
leankg serve --port 8080
# open http://127.0.0.1:8080/

# Terminal B — hot-reload explorer (recommended for local UI work)
cd ui-v2
npm install
npm run dev
# open http://127.0.0.1:5173/?path=src

Vite proxies /api → 127.0.0.1:8080. Status should show connected.
Details: ui-v2/README.md · docs/archive/web-ui.md

---

Enterprise Ready

Peers in this space are mostly personal / single-repo. LeanKG is the company platform: shared index, ops graph, and measured agent economics.

Pillar	Ships as
Multi-repo server	MCP HTTP :9699 (sqlite default; PG opt-in); LEANKG_PROJECT_DIRS
Env governance	env=, promote_environment, find_env_conflicts
Ops & ownership	get_service_graph, query_incidents, get_team_map
Req ↔ code	index_prd, get_traceability, get_traceability_matrix
Mega-graph	Frontier-local queries; 100k–700k+ elements
Agent surface	1 MCP tool (leankg_context) serving ~76 capabilities as verbs; peers typically ~1–17 raw tools
Cost	A/B −65% tokens, −85% tool calls, 2.5× vs grep/cat

Capability	LeanKG	GitNexus	Graphify	Codanna	Context7
Multi-repo team deploy	Yes	Partial	Limited	Limited	n/a
Env / incidents / team map	Yes	No	No	No	No
PRD traceability	Yes	No	Partial	No	No
Mega-graph (100k+)	Yes	Partial	Viz capped	Varies	n/a
MCP depth	77	~17	~10	~5	docs only

Deep dives (archived): ROI vs Graphify · Competitive one-pager · Research matrix

---

Why LeanKG?

Agents normally rebuild structure with grep → open files → huge context. LeanKG returns a targeted subgraph (callers, dependents, blast radius, tests, docs) plus the team layer (env, services, incidents, requirements) over MCP.

Without	With LeanKG
Many tool calls, large context	Surgical subgraph + TOON (~40% smaller payloads)
No blast radius	Severity-graded impact
Keyword only	Keyword + HNSW semantic + ontology
Single-repo guesswork	Multi-repo index + ops tools

---

Key Features

• MCP-native — search, impact, call graphs, ontology, architecture, team knowledge
• SQLite default (zero-config, no Docker) with optional Postgres/pgvector backend; HNSW semantic search (--features embeddings)
• Procedural ontology — hot-reload ontology/workflows.yaml → kg_trace_workflow
• Impact & deps — imports, calls, tested_by, http_calls, service_calls
• Web UI v2 — Force / Tree / Circles explorer (leankg serve + cd ui-v2 && npm run dev)
• Languages — Rust, Go, C/C++, Java, Kotlin, TS/JS, Python, Ruby*, PHP*, Dart, Swift*, ObjC*, Terraform, CI YAML (*depth varies)

---

MCP prefer-order

Discover first — do not open with query_graph:

leankg_context → get_overview_context → mcp_status → concept_search / semantic_search / search_code → impact / deps / get_context

Question	First tools
Any question (default)	leankg_context (intent is auto-classified; degrades L3→L0 instead of erroring)
Fuzzy / domain NL	concept_search → semantic_search → search_code
Exact symbol / file	search_code
How A↔B?	shortest_path
Expand after seeds	query_graph

Catalog: docs/archive/mcp-tools.md · Setup: docs/archive/agentic-instructions.md

---

CLI

leankg init | index ./src | status | update
leankg impact <file> --depth 3
leankg path <from> <to> | explain <symbol> | graph-query "<q>"
leankg embed --init && leankg embed   # --features embeddings
leankg mcp-stdio --watch | mcp-http --port 9699 | serve --port 8080
leankg ontology sync | ontology trace <workflow>

UI hot-reload: cd ui-v2 && npm install && npm run dev → http://127.0.0.1:5173

Full reference: docs/archive/cli-reference.md

---

Docs

The documentation set lives in docs/ — a single unified PRD (docs/prd.md) + task tracker (docs/prd-task-tracker.md). All historical design docs, analyses, reports, and plans are preserved under docs/archive/.

Doc
PRD	Unified product requirements + HLD (single SoT)
Task tracker	Done / in-progress / todo
Architecture (archived)	Design & data model (historical)
MCP tools (archived)	Tool catalog (historical)
CLI (archived)	All commands (historical)
Benchmarks (archived)	Methodology (historical)
Embeddings	HNSW / ops
Postgres migration (archived)	Engine notes (historical)
AGENTS.md	Agent notes

---

Troubleshooting

Issue	Fix
High RAM (macOS)	LEANKG_MMAP_SIZE=134217728 — see INSTRUCTION.md
MCP “not initialized” in Docker	Use container project=/workspace, not the host path
Embeddings / cold embed	src/embeddings/EMBEDDINGS.md

Requirements: macOS or Linux · Docker recommended for teams · Rust 1.75+ only when building from source.

---

Contributing

1. Fork + feature branch (prefer a worktree)
2. Update docs when behavior changes
3. cargo build --release && cargo test
4. Open a PR with summary + test plan

License

Apache License 2.0