LeanKG

Installation

Prerequisites

Postgres + pgvector is required (only storage engine). From a LeanKG checkout:

docker compose up -d postgres   # host :5433

Default URL: postgresql://postgres:postgres@localhost:5433/leankg (override with LEANKG_PG_URL).
One-liners below do not start Postgres — they fail if :5433 is down.

One-liners

# Docker — index + embed + MCP HTTP (Postgres must already be up)
curl -fsSL https://raw.githubusercontent.com/FreePeak/LeanKG/main/scripts/docker-up.sh | bash

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

Skip cold embed: LEANKG_SKIP_EMBED=1 curl -fsSL …/docker-up.sh | bash

Docker (manual)

docker compose up -d          # Postgres :5433 + MCP :9699
# or MCP only (bring your own PG via LEANKG_PG_URL):
docker run -d --name leankg -p 9699:9699 \
  -e LEANKG_PG_URL=postgresql://postgres:postgres@host.docker.internal:5433/leankg \
  -v "$(pwd):/workspace" freepeak/leankg:latest
curl http://localhost:9699/health

MCP URL: http://localhost:9699/mcp

From source

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

Get Started

# 0. Postgres once — point at your instance (or: docker compose up -d postgres)
export LEANKG_PG_URL="postgres://user:pass@host:5432/db"

# 1. Per project: init -> migrate -> index
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 — PG latency, migrations, index freshness, embedding coverage, pool env, 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.

Docker MCP users: pass container paths as project= (e.g. /workspace), never host paths.

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.

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.

Key Features

• MCP-native — search, impact, call graphs, ontology, architecture, team knowledge
• Postgres + pgvector — only storage engine; HNSW semantic search (--features embeddings / Docker)
• 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:

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

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/.