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

Related MCP server: CodeXRay

Get Started

# 1. Postgres (once)
docker compose up -d postgres

# 2. Index your project
leankg setup                 # wire MCP into your agents
cd your-project
leankg init && leankg index ./src && leankg status
leankg impact src/main.rs --depth 3
leankg mcp-stdio --watch     # local agents
leankg mcp-http --port 9699  # HTTP / Docker

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

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/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: 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/mcp-tools.md · Setup: docs/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/cli-reference.md

Docs

Troubleshooting

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