Reduce Claude Code, Codex, OpenCode wall clock and token use by 50% with open source, local semantic search. Works for small and large codebases and monorepos! Enterprise-ready and fully compliant via Ollama and SQLite-vec.
Claude reads entire files to find what it needs. Lumen gives it a map.
Lumen is a 100% local semantic code search engine for AI coding agents. No API
keys, no cloud, no external database, just open-source embedding models
(Ollama or LM Studio), SQLite,
and your CPU. A single static binary and your own local embedding server.
The payoff is measurable and reproducible: across 9 benchmark runs on 9
languages and real GitHub bug-fix tasks, Lumen cuts cost in every single
language — up to 39%. Output tokens drop by up to 66%, sessions complete up to
53% faster, and patch quality is maintained in every task. All verified with a
transparent, open-source benchmark framework that you can
run yourself.
Claude Code asking about the
Prometheus codebase. Lumen's
semantic_search finds the relevant code without reading entire files.
Quick start
Prerequisites:
Platform support: Linux, macOS, and Windows. File locking for background
indexing coordination uses flock(2) on Unix and LockFileEx on Windows
(via gofrs/flock).
Ollama installed and running, then pull the default
embedding model:
Note: Installation differs by platform. Claude Code is installed from a
plugin marketplace. Codex uses a local MCP server plus native skill discovery.
OpenCode installs from npm. Cursor packaging is shipped in this repository and
is ready for Cursor's plugin distribution workflow.
Indexes your project in the background using Merkle tree change detection
Registers a semantic_search MCP tool that the host can use automatically
In Codex and OpenCode, the same binary download and index seeding happen on the
first semantic_search call.
Two shared skills are also available: doctor (health check) and reindex
(forced re-indexing). Claude exposes them as /lumen:doctor and
/lumen:reindex; the other hosts discover the same shared skill content
through their native skill systems.
The same semantic_search, health_check, and index_status MCP tools plus
the shared doctor and reindex skills are exposed through the Codex,
Cursor, and OpenCode surfaces as well. The first semantic_search call seeds
or refreshes the index automatically.
What you get
Semantic vector search — Claude finds relevant functions, types, and
modules by meaning, not keyword matching
Auto-indexing — indexes on session start, only re-processes changed files
via Merkle tree diffing
Incremental updates — re-indexes only what changed; large codebases
re-index in seconds after the first run
Git worktree support — worktrees share index data automatically; a new
worktree seeds from a sibling's index and only re-indexes changed files,
turning minutes of embedding into seconds
Zero cloud — embeddings stay on your machine; no data leaves your network
Ollama and LM Studio — works with either local embedding backend
How it works
Lumen sits between your codebase and Claude as an MCP server. When a session
starts, it walks your project and builds a Merkle tree over file hashes:
only changed files get re-chunked and re-embedded. Each file is split into
semantic chunks (functions, types, methods) using Go's native AST or tree-sitter
grammars for other languages. Chunks are embedded and stored in SQLite +
sqlite-vec using cosine-distance KNN for retrieval.
When Claude needs to understand code, it calls semantic_search instead of
reading entire files. The index is stored outside your repo
(~/.local/share/lumen/<hash>/index.db), keyed by project path and model name —
different models never share an index.
Benchmarks
Lumen is evaluated using bench-swe: a SWE-bench-style harness that runs
Claude on real GitHub bug-fix tasks and measures cost, time, output tokens, and
patch quality — with and without Lumen. All results are reproducible: raw JSONL
streams, patch diffs, and judge ratings are committed to this repository.
Key results — 9 runs across 9 languages, hard difficulty, real GitHub
issues (ordis/jina-embeddings-v2-base-code, Ollama):
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.
