LeanKG - AI Agent Context

Project Overview

LeanKG is a lightweight knowledge graph for codebase understanding. It indexes code, builds dependency graphs, calculates impact radius, and exposes everything via MCP for AI tool integration.

Tech Stack: Rust + CozoDB + tree-sitter + MCP

Quick Start

# Index a codebase
cargo run -- init
cargo run -- index ./src

# Calculate impact radius
cargo run -- impact src/main.rs 3

# Start MCP server
cargo run -- serve

Development Workflow

When implementing features, follow: docs/workflow-opencode-agent.md

Pattern: Update Docs → Implement → Test → Commit → Push → Bump Version → Tag

Update docs first - PRD (docs/requirement/prd-leankg.md) → HLD (docs/design/hld-leankg.md) → README
Implement - Follow patterns in docs/workflow-opencode-agent.md
Build & test - cargo build && cargo test
Commit - git commit -m "feat: description" (one feature per commit)
Push - git pull --rebase && git push
Bump version - Update version in Cargo.toml
Tag - git tag -a v<version> -m "Release v<version>" && git push origin v<version> (after version bump)

Commit Message Rules

NEVER add Co-Authored-By: Claude Opus 4.6 <[email protected]> to commits
NEVER add 🤖 Generated with Claude Code or similar AI attribution
NEVER add "Generated by" phrases in PR descriptions

Key Commands

IMPORTANT: Always use --release flag for builds. Debug builds are disabled.

cargo build --release  # Build project (release)
cargo test             # Run tests
cargo run --release -- <cmd>  # Run CLI commands

Important Files

File	Purpose
`src/lib.rs`	Module exports
`src/db/models.rs`	Data models (CodeElement, Relationship, BusinessLogic)
`src/graph/query.rs`	Graph query engine
`src/mcp/tools.rs`	MCP tool definitions
`src/mcp/handler.rs`	MCP tool handlers
`src/indexer/extractor.rs`	Code parsing with tree-sitter

Data Model

CodeElement - Files, functions, classes with qualified_name (e.g., src/main.rs::main)
Relationship - imports, calls, tested_by, references, documented_by
BusinessLogic - Annotations linking code to business requirements

MCP Tools

Core tools: query_file, get_dependencies, get_dependents, get_impact_radius, get_review_context, find_function, get_call_graph, search_code, generate_doc, find_large_functions, get_tested_by

Doc/Traceability tools: get_doc_for_file, get_files_for_doc, get_doc_structure, get_traceability, search_by_requirement, get_doc_tree, get_code_tree, find_related_docs

Verification Status

See docs/implementation-feature-verification-2026-03-25.md for test results.

LeanKG Tools Usage

MANDATORY: Use LeanKG First, Fallback to Raw Tools

This is a MANDATORY workflow - not optional guidance.

Step 1: Always Try LeanKG First

Call mcp_status to check if LeanKG is ready
If not ready, call mcp_init with path: "/Users/linh.doan/work/harvey/freepeak/leankg/.leankg"
Use appropriate LeanKG tool: search_code, find_function, query_file, get_impact_radius, get_dependencies, get_dependents, get_tested_by, get_context

Step 2: Fallback Only If LeanKG Fails

LeanKG returns empty results OR
LeanKG returns error AND you need the data
THEN you may use Glob, Grep, Read as fallback

Step 3: Never Skip LeanKG for Code Search

NEVER say "I'll just use grep" without trying LeanKG first
NEVER claim "LeanKG doesn't have this" without actually checking

Task	LeanKG First	Fallback
Where is X?	`search_code("X")`	`Grep("X")`
Find function	`find_function("name")`	`Grep("fn name")`
What breaks?	`get_impact_radius(file)`	Manual trace
What tests?	`get_tested_by(file)`	`Grep("test.*file")`
Read content	`get_context(file)`	`Read(file)`

Why This Matters

LeanKG is 10-100x faster than raw grep on large codebases
LeanKG understands code relationships (imports, calls, tests)
Raw tools should be emergency fallback only

MCP Server Management

Known Issues

MCP HTTP stability: Zombie processes and stale locks can accumulate on restart. See docs/analysis/mcp-http-stability-analysis-2026-05-05.md

MCP HTTP Server Commands

# Check if running
lsof -i :9699 2>/dev/null | grep LISTEN

# Verify health
curl http://localhost:9699/health

# Verify SSE endpoint
curl -I http://localhost:9699/mcp/stream

# Clean restart (kill stale processes first)
lsof -ti :9699 | xargs kill -9 2>/dev/null; sleep 1
launchctl stop com.leankg.mcp-http 2>/dev/null; sleep 1
launchctl start com.leankg.mcp-http

# Watch for build changes
./scripts/watch-leankg-build.sh

Last updated: 2026-05-05

Source: FreePeak/LeanKG · 199★ Repo: LeanKG: Stop Burning Tokens. Start Coding Lean.

CLAUDE.md — FreePeak/LeanKG