Lifeblood

Compiler tools and semantic codebase knowledge for AI agents over MCP. Developed for C#, Roslyn and Unity, but with support for other languages since it uses hexagonal architecture.

Lifeblood loads a C# / Unity workspace through Roslyn or a C codebase through the beta libclang adapter, builds a persistent semantic graph with stable symbol IDs, and exposes it to AI agents over MCP, so an agent can ask "what calls this?", "what breaks if I rename it?", "does this edited file still compile?", "which architecture invariant declares this rule?" and get verified answers instead of grep guesses. Every read-side response carries a truth envelope (evidence tier, confidence band, staleness) so the agent knows when an answer is Proven, Advisory, or Speculative.

Roslyn is the C# engine. libclang is the C engine (beta). TypeScript and Python ship as standalone JSON-emitting adapters. Lifeblood is the layer around them: persistent project graph, MCP tool surface, Unity-aware reachability, incremental re-analysis, CI-wireable export and verify commands. Live tool / port / invariant / self-analyze counts: docs/STATUS.md.

Quick Start

Install (30 seconds)

dotnet tool install --global Lifeblood
dotnet tool install --global Lifeblood.Server.Mcp

Requires .NET 8 SDK.

Connect to Claude Code, Cursor, or any MCP client

Add to your project's .mcp.json:

{
  "mcpServers": {
    "lifeblood": {
      "command": "lifeblood-mcp",
      "args": ["--shared"]
    }
  }
}

Shared mode gives same-workspace agents one latest semantic/Roslyn base. See the MCP Setup Guide for lifecycle details, Claude Desktop, VS Code, Cursor, raw stdio configs, and the private-process rollback form.

Use

lifeblood_analyze projectPath="/path/to/your/project"   → load semantic graph
lifeblood_analyze projectPath="/path" excludePaths=["Packages/*","*/Samples*/*"] → drop vendored/sample source before compilation
lifeblood_blast_radius symbolId="type:MyApp.AuthService" → what breaks if I change this?
lifeblood_file_impact filePath="src/AuthService.cs"      → what files are affected?
lifeblood_find_references symbolId="type:MyApp.IRepo"    → every caller, every consumer
lifeblood_search query="quantize timing to grid"         → ranked keyword + xmldoc search
lifeblood_invariant_check id="INV-CANONICAL-001"         → query architectural invariants
lifeblood_compile_check filePath="src/MyFile.cs"         → does this file still compile?
lifeblood_execute code="typeof(MyApp.Foo).GetMethods()"  → run C# against your types

After the first analysis, use incremental: true for fast re-analysis (seconds instead of minutes).

CLI (for CI and scripting)

lifeblood analyze --project /path/to/your/project
lifeblood analyze --project /path/to/your/project --rules hexagonal
lifeblood context --project /path/to/your/project
lifeblood export  --project /path/to/your/project --out graph.json
lifeblood verify  --incremental --project /path/to/your/project

export --out writes the graph JSON to a file directly (preferred over shell redirection on Windows PowerShell, where > defaults to UTF-16-LE-with-BOM and breaks JSON re-import without the INV-JSON-IMPORT-BOM-001 BOM-aware reader). verify --incremental runs full + incremental analyze in one process and asserts summary.edges are identical (INV-INCREMENTAL-XREF-001); non-zero exit on drift makes it CI-wireable.

Build from source

git clone https://github.com/user-hash/Lifeblood.git
cd Lifeblood
dotnet build
dotnet test

MCP Tools

Roslyn (C#)    ──┐                              ┌──  Execute code against project types
libclang (C)   ──┤  ┌────────────────────────┐  ├──  Diagnose / compile-check
TypeScript     ──┼→ │    Semantic Graph      │ →┤──  Find references / rename / format
Python         ──┤  │  (symbols / edges /    │  ├──  Blast radius / file impact
JSON graph     ──┤  │   evidence / trust)    │  └──  Context packs / architecture rules
  community    ──┘  └────────────────────────┘
  adapters

Connect an MCP client. Load a project. The AI agent gets the MCP tool surface: read side + write side (live counts in docs/STATUS.md).

Every read-side tool that takes a symbolId routes through one resolver (canonical id, truncated method form, bare short name, kind correction, wrong-namespace fallback). Every read-side response carries a typed truth envelope: truth tier, confidence band, evidence source, staleness, per-tool limitations.

Full tool reference · What's new

Architecture

Hexagonal. Pure domain core with zero dependencies. Language adapters on the left, AI connectors on the right.

LEFT SIDE                     CORE                     RIGHT SIDE
(Language Adapters)        (The Pipe)               (AI Connectors)

Roslyn (C#)       ──┐                            ┌──  MCP Server (stdio)
libclang (C)      ──┤                            ├──  Context Pack Generator
TypeScript        ──┼→  Domain  →  Application  →┤──  Instruction File Generator
Python            ──┤       ↑                     ├──  CLI / CI
JSON graph        ──┘    Analysis (optional)      └

All port interfaces wired. Boundaries enforced by architecture invariant tests, the typed-invariant tree under docs/invariants/ (queryable via lifeblood_invariant_check), and 11 frozen ADRs. Live counts: docs/STATUS.md.

Source-control provenance is a separate infrastructure boundary: one neutral receipt and Application port are implemented by Lifeblood.Adapters.Git and captured for analyze once at request admission and consumed by invariant evidence plus release ratchets. Language adapters and MCP handlers do not launch Git or own competing dirty-state models.

Full architecture · Interactive diagram

Four Languages, One Graph

Adapter guide · Native C capability

Unity

Lifeblood runs as a sidecar alongside Unity MCP. The Unity bridge exposes a curated in-Editor subset of the MCP tool surface via [McpForUnityTool] discovery; the standalone lifeblood-mcp server exposes the full surface. The sidecar runs as a separate process, with no assembly conflicts and no domain-reload interference. dead_code recognizes Unity reflection dispatch (MonoBehaviour magic methods, full Editor attribute roster, type-via-child propagation) and resolved UnityEvent persistent calls from prefab/scene/asset YAML. compile_check filePath=... resolves the file's owning compilation and swaps the existing tree, so module-owned files compile-check against their real reference set. execute auto-injects DLLs from Library/ScriptAssemblies/.

Unity setup guide

Dogfooding

Self-analysis (symbols, edges, modules, types, violations, cycles), discovered test cases, [SkippableFact] opt-in count, typed-invariant audit (total + category coverage, duplicates, parse warnings) — every metric is anchored in docs/STATUS.md and ratcheted against the live source on every CI run (see tests/Lifeblood.Tests/DocsTests.cs). Zero regressions, zero parse warnings.

Production-verified on large Unity workspaces; current dogfood counts and memory profiles live in Status. Authority report classifies methods across the full surface and identifies forwarder candidates for any host-with-many-subordinates triage (partial-class hosts, dispatchers, facades, ports). Edge count grew +18% over the prior baseline because enum-member references the dangling-edge filter was silently dropping (R2-3) now resolve. 50+ real bugs surfaced through dogfooding — methodology and per-finding history are summarized in Status and the CHANGELOG.

Roadmap

• Native Clang maturity: move from focused-slice scout to whole-build coverage on FFmpeg-class C codebases (WSL + bear, MSYS2 + bear, or a project-specific compile-database generator). Tracked in docs/plans/native-clang-adapter-masterplan-2026-05-16.md.
• C++ over libclang: extend the native adapter past C to C++. Same boundary, additional Clang AST coverage (templates, classes, member functions).
• Community adapters: contribution guides for Go and Rust. Contract and checklist ready, no implementation code yet.
• REST / LSP bridge: expose the graph to IDE extensions and web services.

Documentation

Related

• LivingDocFramework — the methodology that shaped the architecture
• Roslyn — the C# compiler platform
• Case study — the 400k LOC Unity project where these ideas were proven

License

AGPL v3