by ory
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.
# Add to your Claude Code skills
git clone https://github.com/ory/lumen
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.
| | With Lumen | Baseline (no Lumen) | | ---------------------- | ----------------------------- | -------------------- | | Cost (avg, bug-fix) | $0.29 (-26%) | $0.40 | | Time (avg, bug-fix) | 125s (-28%) | 174s | | Output tokens (avg) | (-37%) | 8,323 | | JavaScript (marked) | (-33%, -53%) | $0.48, 255s | | Rust (toml) | (-39%, -34%) | $0.61, 310s | | PHP (monolog) | (-27%, -34%) | $0.19, 52s | | TypeScript (commander) | (-27%, -33%) | $0.19, 84s | | Svelte (chat-ui) | (-26%, -31%) | $0.14, 80s | | Patch quality | | — |
No comments yet. Be the first to share your thoughts!
Claude Code asking about the
Prometheus codebase. Lumen's
semantic_search finds the relevant code without reading entire files.
Prerequisites:
Platform support: Linux, macOS, and Windows. File locking for background indexing coordination uses
flock(2)on Unix andLockFileExon Windows (via gofrs/flock).
ollama pull ordis/jina-embeddings-v2-base-code
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.
Install:
Claude Code
/plugin marketplace add ory/claude-plugins
/plugin install lumen@ory
Verify by starting a new Claude session and running /lumen:doctor.
Cursor
Lumen ships a native Cursor plugin bundle in this repository:
.cursor-plugin/plugin.json - plugin manifestmcp.json - local lumen MCP server wiringhooks/hooks-cursor.json - SessionStart hookskills/ - shared doctor and reindex skillsUse Cursor's plugin installation or distribution workflow with this bundle. Detailed packaging notes: .cursor-plugin/INSTALL.md
Verify by opening a new Cursor agent session and asking it to use the doctor
skill or the Lumen semantic_search tool.
Codex
Quick install:
Fetch and follow instructions from https://raw.githubusercontent.com/ory/lumen/refs/heads/main/.codex/INSTALL.md
Manual install:
CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
git clone https://github.com/ory/lumen.git "$CODEX_HOME/lumen"
mkdir -p "$HOME/.agents/skills"
ln -s "$CODEX_HOME/lumen/skills" "$HOME/.agents/skills/lumen"
codex mcp add lumen -- "$CODEX_HOME/lumen/scripts/run" stdio
Detailed docs: .codex/INSTALL.md
Verify with:
codex mcp get lumen
ls -la "$HOME/.agents/skills/lumen"
OpenCode
Add @ory/lumen-opencode to the plugin array in your opencode.json:
{
"plugin": ["@ory/lumen-opencode"]
}
Detailed docs: .opencode/INSTALL.md
Verify with:
opencode mcp list
Updating
cd "${CODEX_HOME:-$HOME/.codex}/lumen" && git pullopencode.json (e.g.
@ory/lumen-opencode@0.0.29) and restart OpenCodeOn first Claude Code or Cursor session start, Lumen:
semantic_search MCP tool that the host can use automaticallyIn 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.
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.
Files → semantic chunks → vector embeddings → SQLite/sqlite-vec → KNN search
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.
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):
| Language | Cost Reduction | Time Reduction | Output Token Reduction | Quality | | ---------- | -------------- | -------------- | ----------------------- | -------------- | | Rust | -39% | -34% | -31% (18K → 12K) | Poor (both) | | JavaScript | -33% | -53% | -66% (14K → 5K) | Perfect (both) | | TypeScript | -27% | -33% | -64% (5K → 1.8K) | Good (both) | | PHP | -27% | -34% | -59% (1.9K → 0.8K) | Good (both) | | Ruby | -24% | -11% | -9% (6.1K → 5.6K) | Good (both) | | Python | -20% | -29% | -36% (1.7K → 1.1K) | Perfect (both) | | Go | -12% | -9% |