Lurp: a Roslyn semantic map for .NET agents

Windows only, today. Lurp is developed and CI-tested on Windows
(windows-latest); cross-platform support is on the roadmap but not there yet.

Lurp indexes a .NET solution into SQLite with Roslyn, so an agent gets a small,
sufficient code neighborhood instead of re-grepping and re-parsing the whole
thing for every question. It loads the solution through the compiler and stores
symbols, typed relationships, source spans, and provenance in one database, then
serves retrieval, semantic diffs, impact paths, and token-bounded context
capsules. Index once, query as many times as you want, and get back exact
source with evidence levels each time.

What the model sees

An interactive map of how Lurp structures an eCommerce codebase for agent
consumption: symbols, relationships, evidence levels, and capsule boundaries
as the model receives them.

Why this exists

An agent working a C# codebase today loops search → read → guess, reopening and
re-parsing the whole solution for every question. Context windows fill up with
irrelevant source, and the agent ends up rediscovering the same call graph on
every turn.

Lurp flips that cost around. A one-time index builds a snapshot-bound semantic
graph. After that, every query just reads persisted facts: no Roslyn reload, no
re-grep. Capsules return the smallest neighborhood that's actually sufficient
for the task, each fact states its provenance (compiler_proved →
runtime_unknown), and any omitted tier is named so you can fetch it
separately.

The mental model

Worked example

Index a solution, then build a context capsule from a source location:

lurp --mode=index --solution=MySolution.slnx --output-dir=./out
lurp --mode=context --file=src/Services/OrderService.cs --line=42 --output-dir=./out --output=summary

--output=summary prints the handoff facts instead of the full JSON capsule:

capsule OrderService.CreateAsync (Method)
  snapshot: f3bff523b103462be239655c9b753be3  intent: inspect  maxHops: 3
  content tokens:  283/8000  (estimatedTokens: the budget basis)
  delivery tokens: ~571  (estimatedArtifactTokens: whole emitted file; size the context window from this)
  truncated: true
  omitted: direct_callers (budget_exhausted) : fetch with --tier=direct_callers
  omitted: relevant_tests (budget_exhausted) : fetch with --tier=relevant_tests

When a tier is budget_exhausted, fetch it on its own with no budget applied:

lurp --mode=context --file=src/Services/OrderService.cs --line=42 --output-dir=./out --tier=direct_callers

Install

dotnet tool install --global lurp --version 1.4.0
lurp --mode=index --solution=path/to/Your.slnx --output-dir=./out

dotnet build Lurp.slnx
dotnet run --project src -- --mode=index --solution=path/to/Your.slnx --output-dir=./out

Environment variables LURP_SOLUTION_PATH and LURP_OUTPUT_DIR are equivalent to
--solution= and --output-dir=. Requires .NET 10 SDK 10.0.301 (pinned via
src/global.json rollForward=latestMajor; Roslyn 5.6 requires net10.0).

Installing a local build as the global tool: if you pack a local build and its
version number matches the version already on nuget.org, dotnet tool install --global --add-source <path> lurp can silently
install the nuget.org copy instead of yours. --add-source only appends a source;
it does not remove nuget.org, and when two sources offer the same version, NuGet is
free to pick either one. Use --source <path> instead — it replaces every other
source, so only your local build is visible. Confirm afterward with
lurp --version, which prints the schema/extractor/CLI-MCP-contract versions the
installed binary was built with — compare that against the docs you're reading; a
mismatch means dotnet tool install pulled an older published build than the repo
this doc came from. This will bite again on every future local build that reuses
an already-published version number; bump the local package version before packing, or
always install with --source, never --add-source.

Common recipes

Task-first lookup for things you already know Lurp can do but not which mode does it:

Framework adapters

Lurp models framework-mediated relationships through six adapters that emit
ordinary typed facts into the shared model. Each fact retains its evidence level;
see ARCHITECTURE.md for the ladder.

Limitations

• Single active TFM/configuration: one snapshot per index run.
• Source generators not executed: GeneratedTreesIncluded=false; generated files under obj/ are path-filtered out.
• Reflection string-literal candidates are name_candidate, not compiler_proved.
• 3-snapshot retention: older snapshots and their document versions are pruned automatically, except a snapshot pinned via pin-snapshot, which pruning always skips.
• Workspace must be restorable: MSBuildWorkspace requires a successful restore; no index without it.

Performance

Status & roadmap

Shipped as a global tool (dotnet tool install lurp); the published version is
1.4.0. Schema v29, extractor
1.6.0. windows-latest CI plus a self-hosted real-parity gate on FIT-RS2-2026 +
eNoteV2 (opt-in via real-parity PR label). Roadmap: multi-TFM and richer DI
parameter-type matching are postponed by design (see
DeclaredBoundaries).

Documentation & license

• ARCHITECTURE.md: product model, storage, pipeline, rules.
• CLI_REFERENCE.md: commands, options, output shapes, snapshot lifecycle, MCP.
• MIT license, see LICENSE.

Also MCP: --mode=serve exposes 18 tools (lurp_context, lurp_get_source,
lurp_outline, lurp_navigate, lurp_find_symbol, lurp_search, lurp_grep,
lurp_impact, lurp_diff, lurp_get_symbol, lurp_get_annotations, lurp_retract_annotation,
lurp_diagnostics, lurp_status, lurp_timings, lurp_refresh, lurp_index,
lurp_dead_candidates) over stdio; all are read-only except lurp_index and lurp_retract_annotation
(background re-index). Index first, then serve. See
CLI_REFERENCE.md#mcp.