{
  "markdown": "<p align=\"center\">\n  <img src=\"assets/icon.svg\" alt=\"LeanKG\" width=\"128\" height=\"128\">\n</p>\n\n<h1 align=\"center\">LeanKG</h1>\n\n<p align=\"center\">\n  <strong>Enterprise-ready code knowledge graph for AI coding agents</strong><br>\n  Multi-repo · env governance · incidents &amp; services · req↔code · −65% tokens / −85% tool calls\n</p>\n\n<p align=\"center\">\n  <a href=\"https://leankg.onrender.com\"><strong>Live Demo</strong></a>\n  ·\n  <a href=\"docs/prd.md\">Docs</a>\n  ·\n  <a href=\"https://hub.docker.com/r/freepeak/leankg\">Docker Hub</a>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://github.com/FreePeak/LeanKG/blob/main/LICENSE\"><img src=\"https://img.shields.io/badge/License-Apache_2.0-blue.svg\" alt=\"License: Apache 2.0\"></a>\n  <a href=\"https://crates.io/crates/leankg\"><img src=\"https://img.shields.io/crates/v/leankg.svg\" alt=\"crates.io\"></a>\n  <a href=\"https://hub.docker.com/r/freepeak/leankg\"><img src=\"https://img.shields.io/docker/v/freepeak/leankg?label=docker&logo=docker\" alt=\"Docker Hub\"></a>\n  <a href=\"https://github.com/FreePeak/LeanKG/actions\"><img src=\"https://img.shields.io/github/actions/workflow/status/FreePeak/LeanKG/ci.yml?branch=main&label=CI\" alt=\"CI\"></a>\n</p>\n\n<p align=\"center\">\n  <img src=\"assets/banner.svg\" alt=\"LeanKG\" width=\"100%\">\n</p>\n\n---\n\n## Installation\n\n### Prerequisites\n\nPostgres + pgvector is required (only storage engine). From a LeanKG checkout:\n\n```bash\ndocker compose up -d postgres   # host :5433\n```\n\nDefault URL: `postgresql://postgres:postgres@localhost:5433/leankg` (override with `LEANKG_PG_URL`).  \nOne-liners below do **not** start Postgres — they fail if `:5433` is down.\n\n### One-liners\n\n```bash\n# Docker — index + embed + MCP HTTP (Postgres must already be up)\ncurl -fsSL https://raw.githubusercontent.com/FreePeak/LeanKG/main/scripts/docker-up.sh | bash\n\n# Agent — binary + MCP wiring (cursor | claude | opencode | gemini | kilo | antigravity | docker | update)\ncurl -fsSL https://raw.githubusercontent.com/FreePeak/LeanKG/main/scripts/install.sh | bash -s -- cursor\n```\n\nSkip cold embed: `LEANKG_SKIP_EMBED=1 curl -fsSL …/docker-up.sh | bash`\n\n### Docker (manual)\n\n```bash\ndocker compose up -d          # Postgres :5433 + MCP :9699\n# or MCP only (bring your own PG via LEANKG_PG_URL):\ndocker run -d --name leankg -p 9699:9699 \\\n  -e LEANKG_PG_URL=postgresql://postgres:postgres@host.docker.internal:5433/leankg \\\n  -v \"$(pwd):/workspace\" freepeak/leankg:latest\ncurl http://localhost:9699/health\n```\n\nMCP URL: `http://localhost:9699/mcp`\n\n### From source\n\n```bash\ncargo install leankg\n# or: git clone https://github.com/FreePeak/LeanKG.git && cd LeanKG && cargo build --release\n```\n\n---\n\n## Get Started\n\n```bash\n# 0. Postgres once — point at your instance (or: docker compose up -d postgres)\nexport LEANKG_PG_URL=\"postgres://user:pass@host:5432/db\"\n\n# 1. Per project: init -> migrate -> index\ncd your-project\nleankg init && leankg migrate && leankg index ./src\n\n# 2a. Wire up an AI client — one command (also: cursor | codex | gemini)\nleankg connect claude-code           # add --remote http://host:9699 to reuse a shared server\n\n# 2b. ...or serve MCP over HTTP yourself\nleankg mcp-http --port 9699          # GET /health returns 200 when ready\n```\n\nSelf-check any deployment: `leankg doctor --deep` — PG latency, migrations, index freshness,\nembedding coverage, pool env, orphan edges, duplicate names (exit 0 pass / 1 warn / 2 fail).\n\nMeasured timings (`scripts/quickstart_smoke.sh`, run weekly in CI): full e2e smoke **88 s**\nvs a 300 s budget; indexing a small repo takes well under 2 minutes.\n\nDocker MCP users: pass **container** paths as `project=` (e.g. `/workspace`), never host paths.\n\n### Server-side setup pipeline (clone -> index -> embed)\n\n`leankg setup` with no flags keeps the legacy client-side behavior (register\nMCP + hooks). Pass pipeline flags to instead clone a list of repos and index\neach one server-side:\n\n```bash\n# Status: print the resolved repo list without running anything\nLEANKG_REPOS=\"github.com/org/repo-a,github.com/org/repo-b\" leankg setup --status\n\n# Clone + index + embed each repo under LEANKG_CLONE_ROOT (default: cwd)\nLEANKG_REPOS=\"github.com/org/repo-a,github.com/org/repo-b\" \\\n  LEANKG_GIT_REF=main \\\n  LEANKG_CLONE_ROOT=/srv/repos \\\n  leankg setup --clone --index --embed\n```\n\nRepo sources:\n\n- `LEANKG_REPOS` — comma-separated `host/namespace` paths to clone.\n- `LEANKG_PROJECT_DIRS` — comma-separated dirs already mounted on disk\n  (skips clone; falls back to indexing what exists when no git token is set).\n\nEnv knobs: `LEANKG_GIT_HOST` (default `github.com`), `LEANKG_GIT_REF`\n(default `main`), `LEANKG_CLONE_ROOT` / `CLONE_ROOT`, `LEANKG_ENV` (default\n`local`), git token via `GITLAB_TOKEN` / `GIT_TOKEN` / `GITHUB_TOKEN`.\nEach cloned repo gets a minimal `.leankg/leankg.yaml`, then `leankg index`\nand `leankg embed --wait` run inside it. A `setup.done` marker prevents\nre-runs.\n\nSet `LEANKG_SETUP=1` on `leankg mcp-http` to run the same pipeline once after\nthe server binds (spawned as a background task; the server stays healthy).\n\n### Web UI\n\nUI talks REST (`:8080`), not MCP (`:9699`). Start the API, then the Vite app in `ui-v2/`:\n\n```bash\n# Terminal A — REST API (+ embedded UI if assets are in src/embed/)\nleankg serve --port 8080\n# open http://127.0.0.1:8080/\n\n# Terminal B — hot-reload explorer (recommended for local UI work)\ncd ui-v2\nnpm install\nnpm run dev\n# open http://127.0.0.1:5173/?path=src\n```\n\nVite proxies `/api` → `127.0.0.1:8080`. Status should show **connected**.  \nDetails: [ui-v2/README.md](ui-v2/README.md) · [docs/archive/web-ui.md](docs/archive/web-ui.md)\n\n---\n\n## Enterprise Ready\n\nPeers in this space are mostly personal / single-repo. LeanKG is the **company platform**: shared index, ops graph, and measured agent economics.\n\n| Pillar | Ships as |\n| ------ | -------- |\n| Multi-repo server | Docker MCP `:9699` + Postgres/pgvector; `LEANKG_PROJECT_DIRS` |\n| Env governance | `env=`, `promote_environment`, `find_env_conflicts` |\n| Ops & ownership | `get_service_graph`, `query_incidents`, `get_team_map` |\n| Req ↔ code | `index_prd`, `get_traceability`, `get_traceability_matrix` |\n| Mega-graph | Frontier-local queries; 100k–700k+ elements |\n| Agent surface | **1** MCP tool (`leankg_context`) serving ~76 capabilities as verbs; peers typically ~1–17 raw tools |\n| Cost | A/B **−65% tokens**, **−85% tool calls**, **2.5×** vs grep/cat |\n\n| Capability | LeanKG | GitNexus | Graphify | Codanna | Context7 |\n| ---------- | ------ | -------- | -------- | ------- | -------- |\n| Multi-repo team deploy | Yes | Partial | Limited | Limited | n/a |\n| Env / incidents / team map | Yes | No | No | No | No |\n| PRD traceability | Yes | No | Partial | No | No |\n| Mega-graph (100k+) | Yes | Partial | Viz capped | Varies | n/a |\n| MCP depth | 77 | ~17 | ~10 | ~5 | docs only |\n\nDeep dives (archived): [ROI vs Graphify](docs/archive/reports/leankg-vs-graphify-company-roi-2026-07-21.md) · [Competitive one-pager](docs/archive/competitive-analysis.md) · [Research matrix](docs/archive/analysis/leankg-competitive-research-and-improvement-strategy-2026-08-02.md)\n\n---\n\n## Why LeanKG?\n\nAgents 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.\n\n| Without | With LeanKG |\n| ------- | ----------- |\n| Many tool calls, large context | Surgical subgraph + TOON (~40% smaller payloads) |\n| No blast radius | Severity-graded impact |\n| Keyword only | Keyword + HNSW semantic + ontology |\n| Single-repo guesswork | Multi-repo index + ops tools |\n\n---\n\n## Key Features\n\n- **MCP-native** — search, impact, call graphs, ontology, architecture, team knowledge\n- **Postgres + pgvector** — only storage engine; HNSW semantic search (`--features embeddings` / Docker)\n- **Procedural ontology** — hot-reload `ontology/workflows.yaml` → `kg_trace_workflow`\n- **Impact & deps** — `imports`, `calls`, `tested_by`, `http_calls`, `service_calls`\n- **Web UI v2** — Force / Tree / Circles explorer (`leankg serve` + `cd ui-v2 && npm run dev`)\n- **Languages** — Rust, Go, C/C++, Java, Kotlin, TS/JS, Python, Ruby*, PHP*, Dart, Swift*, ObjC*, Terraform, CI YAML (*depth varies)\n\n---\n\n## MCP prefer-order\n\nDiscover first — do **not** open with `query_graph`:\n\n`leankg_context` → `get_overview_context` → `mcp_status` → `concept_search` / `semantic_search` / `search_code` → impact / deps / `get_context`\n\n| Question | First tools |\n| -------- | ----------- |\n| Any question (default) | `leankg_context` (intent is auto-classified; degrades L3→L0 instead of erroring) |\n| Fuzzy / domain NL | `concept_search` → `semantic_search` → `search_code` |\n| Exact symbol / file | `search_code` |\n| How A↔B? | `shortest_path` |\n| Expand after seeds | `query_graph` |\n\nCatalog: [docs/archive/mcp-tools.md](docs/archive/mcp-tools.md) · Setup: [docs/archive/agentic-instructions.md](docs/archive/agentic-instructions.md)\n\n---\n\n## CLI\n\n```bash\nleankg init | index ./src | status | update\nleankg impact <file> --depth 3\nleankg path <from> <to> | explain <symbol> | graph-query \"<q>\"\nleankg embed --init && leankg embed   # --features embeddings\nleankg mcp-stdio --watch | mcp-http --port 9699 | serve --port 8080\nleankg ontology sync | ontology trace <workflow>\n```\n\nUI hot-reload: `cd ui-v2 && npm install && npm run dev` → http://127.0.0.1:5173\n\nFull reference: [docs/archive/cli-reference.md](docs/archive/cli-reference.md)\n\n---\n\n## Docs\n\nThe documentation set lives in [`docs/`](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/`](docs/archive/).\n\n| Doc | |\n| --- | --- |\n| [PRD](docs/prd.md) | Unified product requirements + HLD (single SoT) |\n| [Task tracker](docs/prd-task-tracker.md) | Done / in-progress / todo |\n| [Architecture (archived)](docs/archive/architecture.md) | Design & data model (historical) |\n| [MCP tools (archived)](docs/archive/mcp-tools.md) | Tool catalog (historical) |\n| [CLI (archived)](docs/archive/cli-reference.md) | All commands (historical) |\n| [Benchmarks (archived)](docs/archive/benchmark.md) | Methodology (historical) |\n| [Embeddings](src/embeddings/EMBEDDINGS.md) | HNSW / ops |\n| [Postgres migration (archived)](docs/archive/analysis/pg-migration-report.md) | Engine notes (historical) |\n| [AGENTS.md](AGENTS.md) | Agent / Docker notes |\n\n---\n\n## Troubleshooting\n\n| Issue | Fix |\n| ----- | --- |\n| High RAM (macOS) | `LEANKG_MMAP_SIZE=134217728` — see [INSTRUCTION.md](INSTRUCTION.md) |\n| MCP “not initialized” in Docker | Use container `project=/workspace`, not the host path |\n| Embeddings / cold embed | [src/embeddings/EMBEDDINGS.md](src/embeddings/EMBEDDINGS.md) |\n\n**Requirements:** macOS or Linux · Docker recommended for teams · Rust 1.75+ only when building from source.\n\n---\n\n## Contributing\n\n1. Fork + feature branch (prefer a worktree)\n2. Update docs when behavior changes\n3. `cargo build --release && cargo test`\n4. Open a PR with summary + test plan\n\n## License\n\n[Apache License 2.0](LICENSE)\n",
  "bytes": 11138,
  "sha": "134bef50a6e6ff6e930d8c8c8428e1b5517235dd21802008fbe2419e2c5143ba",
  "repo_slug": "freepeak/leankg",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_freepeak_leankg_lean_kg_5cd858b6/readme"
}