Documentation

Lumos in one minute

Lumos is the preflight and verification layer an IDE assistant calls around an edit. Word search finds likely names. HydraDB proves structural impact. Patch Guard checks what the agent actually changed.

Ranked context: The smallest set of files likely to matter for the requested change.
Graph proof: The calls and coverage relationships behind each recommendation.
Test impact: The checks connected to the symbols an agent is about to touch.
Patch Guard: A post-edit verdict on target coverage, unexpected scope, and connected tests.

Quick start

Run Lumos locally with Node 20.11 or newer, pnpm, and Docker.

Install

git clone <this-repo>
cd lumos
cp .env.example .env
pnpm install

Set HOST_UID and HOST_GID in .env to the output of id -u and id -g.

Start HydraDB

pnpm db:up
pnpm probe

db:up waits for a real query to succeed. probe verifies the full write and traversal path.

Expected signal

The setup is ready when the terminal prints hydradb-ok and probe-ok.

Index a repository

Lumos currently extracts Python repositories. Give the indexer a local checkout and an optional stable slug.

pnpm lumos index /path/to/repo --slug owner/name

The indexer extracts files, symbols, definitions, imports, calls, test coverage, and co-change relationships before loading them into HydraDB.

Preflight a change

Describe the task as you would describe it to a coding agent. A bug report, issue, or stack trace all work.

pnpm lumos preflight "Changing set_cookie breaks signed cookie tests"

Targets

Files and symbols ordered by relevance.

Reasons

Why each target belongs in the context.

Evidence

The HydraDB relationship path.

Tests

Checks likely to protect the change.

Verify the agent's patch

After the edit, report the repository-relative files that changed and the tests the agent ran.

pnpm lumos verify "Changing set_cookie breaks signed cookie tests" \
  --changed django/http/response.py \
  --tests responses.test_cookie

Patch Guard blocks a missing primary target and asks for review when the patch leaves the preflight shortlist or omits a connected test. It does not claim to execute the tests or inspect the diff contents.

Inspect impact directly

Use a qualified symbol when you already know the center of the change.

pnpm lumos impact django.http.response.HttpResponseBase.set_cookie
pnpm lumos tests django.http.response.HttpResponseBase.set_cookie

The impact command walks the blast radius. The tests command narrows the result to connected coverage.

Connect an IDE agent with MCP

Run the stdio server from the repository and point your MCP client at the same command.

{
  "mcpServers": {
    "lumos": {
      "command": "pnpm",
      "args": ["mcp"],
      "cwd": "/absolute/path/to/lumos"
    }
  }
}

Cursor, Claude Code, Codex, and other MCP clients can call lumos.preflight_change before an edit and lumos.verify_patch after it.

Available MCP tools

lumos.preflight_change

Run before editing. Return ranked files, graph proof, connected tests, a context contract, and its digest.

lumos.verify_patch

Run after editing. Check the changed files and reported tests against a fresh graph-backed preflight.

lumos.find_relevant_files

Turn an issue into ranked files, reasons, graph evidence, and likely tests.

lumos.explain_file_rank

Explain why one file appears at its position for a specific issue.

lumos.impact

Walk callers, callees, and coverage around a named symbol.

lumos.tests_for_change

Find tests connected to a symbol through the HydraDB graph.

How proof paths work

Lumos starts with names found in the issue, resolves them to symbols, and asks HydraDB for bounded relationship paths. The full path stays attached to the ranked result.

Resolve intentExtract named behavior from the request.
Seed the graphMatch that behavior to repository symbols.
Walk impactTraverse calls and coverage with algo.MSpaths.
Return evidenceRank the context and keep the relationship chain.

Evaluate retrieval

Compare word search, graph-only retrieval, and the hybrid ranker against SWE-bench Lite gold files.

pnpm eval data/swebench/lite.jsonl --repo django/django --root data/repos/django

pnpm db:restore

Read the comparison honestly.

BM25 finds names. The graph matters when repository structure provides evidence that text similarity cannot express.

Troubleshooting

HydraDB is not ready

Run pnpm db:up, wait for hydradb-ok, then verify the connection with pnpm probe.

The demo graph disappeared after evaluation

The evaluation run resets the live graph. Restore the Django snapshot with pnpm db:restore.

The web interface has no live results

Start the HydraDB-backed API with pnpm api, then run the site with pnpm web.

Context your agent can inspect.