LiLBrain

Instant codebase knowledge graph MCP server.

Drop it into any project. It auto-detects languages, indexes every function, class, and call chain, then serves it all through MCP (Model Context Protocol) — so your LLM can navigate code in milliseconds instead of reading thousands of lines.

Why

Reading 5,000 lines to understand a call chain costs ~50K tokens. One graph query costs ~200 tokens. That's a 250x cost reduction.

LiLBrain turns any codebase into a queryable knowledge graph with zero configuration.

Supported Languages (20+)

Python, Rust, Go, TypeScript, JavaScript, Java, C, C++, C#, Ruby, PHP, Swift, Kotlin, Scala, Zig, Lua, Elixir, Dart, Vortex — plus aliases (.jsx, .tsx, .mjs, .hpp, .cc, .exs).

Install

pip install lilbrain

Or clone:

git clone https://github.com/MangoByteLabs/LiLBrain.git
cd LiLBrain
pip install -e .

Quick Start

As MCP Server (for Claude, etc.)

Add to your .mcp.json:

{
  "mcpServers": {
    "lilbrain": {
      "command": "lilbrain",
      "args": ["/path/to/your/project"]
    }
  }
}

Or with Python directly:

{
  "mcpServers": {
    "lilbrain": {
      "command": "python3",
      "args": ["-m", "lilbrain", "/path/to/your/project"]
    }
  }
}

CLI Mode

# Stats overview
lilbrain /path/to/project --stats

# Quick function lookup
lilbrain /path/to/project --query main

# Dump full graph JSON
lilbrain /path/to/project --dump

What It Indexes

Feature	Description
Functions	Name, params, return type, location, docstring, complexity scores
Classes	Structs, enums, traits, interfaces, modules
Call Graph	Who calls whom — full caller/callee edges
Subsystems	Auto-classified from directory structure
Pipelines	Auto-detected from function naming patterns
Constants	UPPER_CASE constants, typed consts, finals
Cross-edges	Cross-subsystem dependency map
Sections	Code sections marked with // SECTION or # SECTION
Complexity	Cyclomatic + cognitive complexity per function
Semantic Index	TF-IDF vectors for meaning-based search

MCP Tools (24)

Core Graph (12)

Tool	Description
lilbrain_overview	Project summary: files, functions, languages, subsystems
lilbrain_function	Look up any function — signature, location, callers, callees
lilbrain_callers	Full call graph for a function
lilbrain_search	Search everything: functions, classes, sections, constants
lilbrain_file	File info: functions, classes, sections, language
lilbrain_read	Read source code of a function or file region
lilbrain_subsystem	Deep dive into a subsystem
lilbrain_pipeline	Trace a pipeline (parse, validate, compile, etc.)
lilbrain_dataflow	Upstream callers and downstream callees
lilbrain_trace	Depth-limited call chain trace
lilbrain_hotspots	Most connected functions (highest fan-in + fan-out)
lilbrain_architecture	Architecture map: subsystems and cross-dependencies

Impact & Quality (4)

Tool	Description
lilbrain_impact	Blast radius analysis — change a function, see everything affected
lilbrain_deadcode	Find functions with zero callers + LOC waste estimate
lilbrain_clones	Detect near-duplicate functions (token Jaccard similarity)
lilbrain_diagram	Auto-generate Mermaid or D2 architecture diagrams

Intelligence (4)

Tool	Description
lilbrain_complexity	Cyclomatic + cognitive complexity ranking
lilbrain_complexity_velocity	Track complexity changes over git history
lilbrain_semantic	Semantic search — find functions by meaning, not name
lilbrain_federation	Multi-repo federated search across codebases

Tier 3 — AI-Native (4)

Tool	Description
lilbrain_ask	Natural language questions — auto-routes to the right analysis
lilbrain_diff	Git-aware graph diff: changed functions, blast radius, risk
lilbrain_pr_review	Auto-generate PR review context with risk assessment
lilbrain_runtime	Correlate OpenTelemetry traces with static call graph

Features

Impact Analysis

Change a function? LiLBrain tells you exactly what breaks:

lilbrain_impact("parse_request")
→ 47 functions affected across 5 subsystems
→ Risk: HIGH
→ Subsystems: api, auth, middleware, handlers, tests

Auto Architecture Diagrams

Generate always-accurate Mermaid diagrams from live code:

lilbrain_diagram("architecture")
→ graph TD
      api["api\n120 fns | 3400 LOC"]
      auth["auth\n45 fns | 1200 LOC"]
      api -->|12| auth

Dead Code & Clone Detection

lilbrain_deadcode()
→ 847/3200 functions unreachable (26.5%)
→ 12,400 LOC wasted

lilbrain_clones()
→ adam_step <-> adamw_step (88.5% similar)
→ tcp_recv <-> udp_recv (83.3% similar)

Semantic Search

Find functions by what they do, not what they're named:

lilbrain_semantic("handle user authentication")
→ verify_token (auth/jwt.py:45) score=14.2
→ check_session (middleware/session.rs:120) score=11.8
→ validate_credentials (api/login.go:33) score=9.4

Natural Language Queries

lilbrain_ask("what is the most complex code?")
→ eval_stmt: cyclomatic=189, cognitive=198
→ lex: cyclomatic=171, cognitive=182

lilbrain_ask("show me dead code")
→ 847 functions with zero callers...

lilbrain_ask("who calls parse_request?")
→ handle_http, route_api, middleware_chain...

Git Time-Travel & PR Review

lilbrain_diff("main", "feature-branch")
→ 12 files changed, 34 functions modified
→ Blast radius: 156 functions affected
→ Risk: HIGH
→ New cross-subsystem edge: api -> payments (didn't exist before!)

lilbrain_pr_review()
→ **8 files changed**, **23 functions modified**
→ **Blast radius**: 89 functions potentially affected
→ **Risk**: MEDIUM
→ **New cross-subsystem edges**: auth -> billing
→ **Complexity in changed code**: 45

Multi-Repo Federation

Search across all your repos at once:

lilbrain_federation(query="authenticate", repos=["/app/api", "/app/auth", "/app/gateway"])
→ api: 3 matches
→ auth: 12 matches
→ gateway: 5 matches

Runtime Correlation

Connect static analysis to production reality:

lilbrain_runtime(trace_dir="traces/")
→ Hot paths: handle_request (45,000 calls, avg 2.3ms)
→ Cold code: legacy_handler (0 invocations — truly dead)

Auto-Reindex

LiLBrain watches for file changes and a .graph-dirty sentinel file. Touch .graph-dirty in your project root (e.g., from a git post-commit hook) and the graph rebuilds automatically on the next query.

# Add to .git/hooks/post-commit:
touch .graph-dirty

Performance

Project Size	Files	Functions	Index Time
Small (1K LOC)	~10	~40	<0.1s
Medium (50K LOC)	~200	~2,000	~0.5s
Large (360K LOC)	~550	~16,800	~2.2s

Zero dependencies. Pure Python 3.10+. Works everywhere.

How It Works

1. Walk — recursively finds all source files, skipping node_modules, .git, __pycache__, etc.
2. Detect — identifies language from file extension, loads the right regex patterns
3. Extract — pulls out functions, classes, sections, constants from each file
4. Connect — builds a call graph by scanning function bodies for known function names
5. Analyze — computes complexity scores, builds TF-IDF semantic index
6. Classify — auto-groups files into subsystems based on directory structure
7. Serve — exposes everything through 24 MCP tools over JSON-RPC stdin/stdout

License

MIT