{"id":48971288,"url":"https://github.com/user-hash/lifeblood","last_synced_at":"2026-04-27T01:02:05.906Z","repository":{"id":349791393,"uuid":"1203918151","full_name":"user-hash/Lifeblood","owner":"user-hash","description":"Compiler truth in, AI context out. Open semantic glue between language intelligence and AI tools.","archived":false,"fork":false,"pushed_at":"2026-04-26T21:24:36.000Z","size":8766,"stargazers_count":6,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-26T21:28:26.795Z","etag":null,"topics":["ai-agents","ai-tools","architecture","claude-code","code-analysis","code-execution","compiler","compiler-as-a-service","csharp","dependency-graph","dotnet","hexagonal-architecture","mcp","model-context-protocol","python","refactoring","roslyn","semantic-analysis","static-analysis","typescript"],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/user-hash.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-07T14:08:41.000Z","updated_at":"2026-04-26T21:24:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/user-hash/Lifeblood","commit_stats":null,"previous_names":["user-hash/lifeblood"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/user-hash/Lifeblood","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/user-hash%2FLifeblood","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/user-hash%2FLifeblood/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/user-hash%2FLifeblood/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/user-hash%2FLifeblood/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/user-hash","download_url":"https://codeload.github.com/user-hash/Lifeblood/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/user-hash%2FLifeblood/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32318417,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T23:26:28.701Z","status":"ssl_error","status_checked_at":"2026-04-26T23:26:25.802Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-tools","architecture","claude-code","code-analysis","code-execution","compiler","compiler-as-a-service","csharp","dependency-graph","dotnet","hexagonal-architecture","mcp","model-context-protocol","python","refactoring","roslyn","semantic-analysis","static-analysis","typescript"],"created_at":"2026-04-18T07:30:59.323Z","updated_at":"2026-04-27T01:02:05.900Z","avatar_url":"https://github.com/user-hash.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lifeblood\n\nCompiler-as-a-service for AI agents.\n\nLifeblood gives AI agents direct access to what compilers know. Type resolution, call graphs, diagnostics, reference finding, code execution. All over a standard MCP connection. No IDE required. Load a project, ask the compiler, get verified answers. \nCompilers already know everything about your code, just pipe that truth to AI agents instead of letting them grep and guess.\n\n```\nRoslyn (C#)    ──┐                              ┌──  Execute code against project types\nTypeScript     ──┤  ┌────────────────────────┐  ├──  Diagnose / compile-check\nJSON graph     ──┼→ │    Semantic Graph      │ →┤──  Find references / rename / format\n               ──┤  │  (symbols / edges /    │  ├──  Blast radius / file impact\n  community    ──┘  │   evidence / trust)    │  └──  Context packs / architecture rules\n  adapters          └────────────────────────┘\n```\n\nBorn from shipping a [400k LOC Unity project](https://github.com/user-hash/LivingDocFramework/blob/main/docs/CASE_STUDY.md) with AI assistance and realizing that AI writes code but does not verify what it wrote.\n\n---\n\n## Quick Start\n\n### Install (30 seconds)\n\n```bash\ndotnet tool install --global Lifeblood\ndotnet tool install --global Lifeblood.Server.Mcp\n```\n\nRequires [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0).\n\n### Connect to Claude Code, Cursor, or any MCP client\n\nAdd to your project's `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"lifeblood\": {\n      \"command\": \"lifeblood-mcp\",\n      \"args\": []\n    }\n  }\n}\n```\n\nSee [MCP Setup Guide](docs/MCP_SETUP.md) for Claude Desktop, VS Code, Cursor, and raw stdio configs.\n\n### Use\n\n```\nlifeblood_analyze projectPath=\"/path/to/your/project\"   → load semantic graph\nlifeblood_blast_radius symbolId=\"type:MyApp.AuthService\" → what breaks if I change this?\nlifeblood_file_impact filePath=\"src/AuthService.cs\"      → what files are affected?\nlifeblood_find_references symbolId=\"type:MyApp.IRepo\"    → every caller, every consumer\nlifeblood_search query=\"quantize timing to grid\"         → ranked keyword + xmldoc search\nlifeblood_invariant_check id=\"INV-CANONICAL-001\"         → query architectural invariants from CLAUDE.md\nlifeblood_compile_check code=\"var x = 1 + 1;\"            → snippet compiles, auto-wraps for library modules\nlifeblood_execute code=\"typeof(MyApp.Foo).GetMethods()\"  → run C# against your types\n```\n\nAfter the first analysis, use `incremental: true` for fast re-analysis (seconds instead of minutes).\n\n### CLI (for CI and scripting)\n\n```bash\nlifeblood analyze --project /path/to/your/project\nlifeblood analyze --project /path/to/your/project --rules hexagonal\nlifeblood context --project /path/to/your/project\nlifeblood export  --project /path/to/your/project \u003e graph.json\n```\n\n### Build from source\n\n```bash\ngit clone https://github.com/user-hash/Lifeblood.git\ncd Lifeblood\ndotnet build\ndotnet test\n```\n\n---\n\n## 25 Tools\n\nConnect an MCP client. Load a project. The AI agent gets **25 tools**: 15 read, 10 write.\n\n| | Tools |\n|---|---|\n| **Read** | Analyze, Context, Lookup, Dependencies, Dependants, Blast Radius, File Impact, Resolve Short Name, Search, Dead Code¹, Partial View, Invariant Check, Authority Report, Port Health, Cycles |\n| **Write** | Execute, Diagnose, Compile-check, Find References, Find Definition, Find Implementations, Symbol at Position, Documentation, Rename, Format |\n\n¹ `lifeblood_dead_code` is experimental / advisory. The reachability port (`IUnityReachabilityProvider`, v0.6.7) cuts MonoBehaviour magic-method false positives by 97% on real Unity workspaces by walking the type's inheritance chain via `Properties[\"baseType\"]` (set by the extractor) and matching against the Unity message-receiver bases. Dogfood vs DAWG (87 modules, 53,882 symbols): 1095 dead-code findings reduced to 729 (-33%), 378 magic-method FPs reduced to 13. Remaining false positives are structural (UI Toolkit `VisualElement` subclasses, audio callbacks on non-MonoBehaviour bases, reflection-based dispatch). See `INV-UNITY-001` and `INV-DEADCODE-001` in [CLAUDE.md](CLAUDE.md).\n\nEvery read-side tool that takes a `symbolId` routes through one resolver. Exact canonical id, truncated method form, bare short name, kind correction (`method:NS.Type.X` resolves to a property/field/event named `X` when no method exists; v0.6.6 / `INV-RESOLVER-006`), and wrong-namespace-correct-short-name (v0.6.3 / `INV-RESOLVER-005`) all resolve to the same answer.\n\nEvery read-side response carries a typed truth envelope (v0.6.7 / `INV-ENVELOPE-001`): truth tier (Semantic / Derived / Heuristic / Inferred), confidence band (Proven / Advisory / Speculative), evidence-source string, wall-clock staleness in seconds, files-changed-since-analyze count, per-tool documented limitations.\n\n**New since v0.6.5 (P1..P6 of the DAWG-dogfood plan):**\n- **Truth envelope** on every read-side response (P2).\n- **Unity-aware reachability** + asmdef-edit incremental detection (P3).\n- **Execute robustness**: Unity DLL probe (`Library/ScriptAssemblies`, `Library/Bee/artifacts`, `Library/PackageCache`), `targetProfile` for runtime ref-pack selection (`host` / `net-standard-2.1` / `net-6.0`), sandbox introspection helpers `Help` / `SymbolsOfKind(string)` / `EdgesOfKind(string)` (P4).\n- **Authority + port health + cycles tools** plus a forwarder classifier on every method (`PureForwarder` / `ThinWrapper` / `RealLogic`) (P5).\n- **Resolver kind correction**, file-scoped diagnose, `compile_check` from disk, `blast_radius` summarize mode + direct-vs-transitive split (P1).\n\n[Full tool reference](docs/TOOLS.md)\n\n---\n\n## Architecture\n\nHexagonal. Pure domain core with zero dependencies. Language adapters on the left, AI connectors on the right.\n\n```\nLEFT SIDE                     CORE                     RIGHT SIDE\n(Language Adapters)        (The Pipe)               (AI Connectors)\n\nRoslyn (C#)       ──┐                            ┌──  MCP Server (25 tools)\nTypeScript        ──┼→  Domain  →  Application  →┤──  Context Pack Generator\nJSON graph        ──┘       ↑                     ├──  Instruction File Generator\n                      Analysis (optional)         └──  CLI / CI\n```\n\n26 port interfaces, all wired (left-side adapters + right-side connectors + `ISymbolResolver` for identifier resolution + `IResponseDecorator` for truth envelope + `IInvariantProvider` for CLAUDE.md invariant introspection + `IUnityReachabilityProvider` for runtime-dispatch reachability + `IRuntimeAssemblyResolver` for execute-time DLL probing + `IAuthorityReporter` for type-level authority reports). Boundaries enforced by [architecture invariant tests](tests/Lifeblood.Tests/ArchitectureInvariantTests.cs), 70 typed invariants in [CLAUDE.md](CLAUDE.md) (queryable via `lifeblood_invariant_check`), and [11 frozen ADRs](docs/ARCHITECTURE_DECISIONS.md).\n\n![Architecture Diagram](docs/architecture-screenshot.png)\n\n[Full architecture](docs/ARCHITECTURE.md) | [Interactive diagram](docs/architecture.html)\n\n---\n\n## Three Languages, One Graph\n\n| Adapter | How it works | Confidence |\n|---------|-------------|------------|\n| **C# / Roslyn** | Compiler-grade semantic analysis. Cross-module resolution. Bidirectional: analysis + code execution. | Proven |\n| **TypeScript** | Standalone Node.js. `ts.createProgram` + `TypeChecker`. | High |\n| **Python** | Standalone `ast` module. Zero dependencies. | Structural |\n| **Any language** | Output JSON conforming to `schemas/graph.schema.json`. [Adapter guide](docs/ADAPTERS.md). | Varies |\n\n---\n\n## Unity Integration\n\nLifeblood runs as a sidecar alongside [Unity MCP](https://github.com/CoplayDev/MCPForUnity). All 25 tools available in the Unity Editor via `[McpForUnityTool]` discovery. Runs as a separate process, so no assembly conflicts, no domain reload interference.\n\n`lifeblood_dead_code` recognizes Unity message-dispatch patterns automatically: `MonoBehaviour` magic methods (`Awake`, `Update`, `OnTriggerEnter`, full Unity catalog), entrypoint attributes (`RuntimeInitializeOnLoadMethod`, `MenuItem`, `ContextMenu`, `CustomEditor`, ...), transitive bases (`ScriptableObject`, `Editor`, `EditorWindow`, `StateMachineBehaviour`). `lifeblood_execute` auto-injects DLLs from `Library/ScriptAssemblies/`, `Library/Bee/artifacts/`, and `Library/PackageCache/` so scripts can touch `UnityEngine` types without Unity being open.\n\n[Unity setup guide](docs/UNITY.md)\n\n---\n\n## Dogfooding\n\nSelf-analysis (MCP, post P1..P6): 2,132 symbols, 9,908 edges, 11 modules, 262 types, 0 violations, 0 cycles. The DAWG-dogfood plan landed in six phases (P1..P6); each phase shipped with a repeatable end-to-end MCP smoke harness (`smoke-mcp-p1-dogfood.ps1` ... `smoke-mcp-p5-dogfood.ps1`). 632 tests across `Lifeblood.Tests`, zero regressions across the plan.\n\nLifeblood audits its own architectural invariants via `lifeblood_invariant_check` against [CLAUDE.md](CLAUDE.md): 70 typed invariants, zero duplicate ids, zero parse warnings.\n\nProduction-verified on a 87-module 400k LOC Unity workspace (DAWG): 53,882 symbols, 180,814 edges. Authority report classifies 18,985 methods, identifies 3,367 `PureForwarder` candidates for ABG-extraction triage. Cycles tool surfaces 117 strongly-connected components in the existing dependency graph. Same workspace, two different paths, two different memory profiles. Both are correct, both are by design, both come from the native `usage` field on every `lifeblood_analyze` response.\n\n| Path | Wall | CPU total | CPU % (1 core) | Peak working set | Use when |\n|---|---|---|---|---|---|\n| **CLI** (streaming, compilations released) | ~14 s | ~23 s | ~150% | ~570 MB | One-shot analyze, rules check, graph export. |\n| **MCP** (compilations retained) | ~32 s | ~58 s | ~180% | ~2,800 MB | Interactive session with write-side tools (`execute`, `find_references`, `rename`, ...). |\n\nThe MCP retained profile sits around 4x the CLI streaming profile because the write-side tools need the loaded workspace in memory to answer follow-up queries. Pass `readOnly: true` to `lifeblood_analyze` to drop MCP back to the streaming profile in exchange for no write-side tools. Both measured on AMD Ryzen 9 5950X (16 cores / 32 threads). Exact numbers are surfaced live on every `lifeblood_analyze` response via the `usage` field so they can be cited deterministically.\n\nMultiple dogfood sessions found [50+ real bugs](docs/DOGFOOD_FINDINGS.md) invisible to unit tests, including the v0.6.3 resolver wrong-namespace fallback (`INV-RESOLVER-005`), the v0.6.6 resolver kind-correction (`INV-RESOLVER-006`), the v0.6.7 truth envelope (`INV-ENVELOPE-001`), the v0.6.7 Unity reachability port (`INV-UNITY-001`, 97% MonoBehaviour-FP reduction on DAWG), the asmdef-edit incremental detection (`INV-UNITY-002`), the `compile_check` library-module auto-wrap, and the `lifeblood_dead_code` false-positive classes tracked under `INV-DEADCODE-001`.\n\n---\n\n## Roadmap\n\n- **Community adapters**: contribution guides for [Go](adapters/go/) and [Rust](adapters/rust/). Contract and checklist ready, no implementation code yet.\n- **REST / LSP bridge**: expose the graph to IDE extensions and web services.\n\n---\n\n## Documentation\n\n| Page | Description |\n|------|-------------|\n| [Tools](docs/TOOLS.md) | All 25 tools with descriptions, symbol ID format, incremental usage, dead_code caveats |\n| [MCP Setup](docs/MCP_SETUP.md) | Copy-paste configs for Claude Code, Cursor, VS Code, Claude Desktop, Unity |\n| [Unity Integration](docs/UNITY.md) | Sidecar architecture, setup guide, incremental, memory, Unity reachability port |\n| [Architecture](docs/ARCHITECTURE.md) | Hexagonal structure, dependency flow, 26 port interfaces, invariants |\n| [Architecture Decisions](docs/ARCHITECTURE_DECISIONS.md) | 11 frozen ADRs |\n| [Invariants](CLAUDE.md) | 70 typed architectural invariants, queryable via `lifeblood_invariant_check` |\n| [Status](docs/STATUS.md) | Component table, test counts (632), self-analysis, production stats |\n| [Adapters](docs/ADAPTERS.md) | How to build a language adapter (13-item checklist) |\n| [Dogfood Findings](docs/DOGFOOD_FINDINGS.md) | 50+ bugs found by self-analysis and reviewer dogfood sessions |\n| [CHANGELOG](CHANGELOG.md) | Every release: additions, fixes, known limitations |\n\n---\n\n## Related\n\n- [LivingDocFramework](https://github.com/user-hash/LivingDocFramework): The methodology that shaped the architecture\n- [Roslyn](https://github.com/dotnet/roslyn): The C# compiler platform\n- [Case study](https://github.com/user-hash/LivingDocFramework/blob/main/docs/CASE_STUDY.md): The 400k LOC Unity project where we proved these ideas\n\n## License\n\nAGPL v3\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuser-hash%2Flifeblood","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuser-hash%2Flifeblood","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuser-hash%2Flifeblood/lists"}