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)	5,247 (-37%)	8,323
JavaScript (marked)	$0.32, 119s (-33%, -53%)	$0.48, 255s
Rust (toml)	$0.38, 204s (-39%, -34%)	$0.61, 310s
PHP (monolog)	$0.14, 34s (-27%, -34%)	$0.19, 52s
TypeScript (commander)	$0.14, 56s (-27%, -33%)	$0.19, 84s
Svelte (chat-ui)	$0.10, 56s (-26%, -31%)	$0.14, 80s
Patch quality	Maintained in all 9 tasks	—

Table of contents

• Demo
• Quick start
• What you get
• How it works
• Benchmarks
• Supported languages
• Configuration
  • Supported embedding models
• Controlling what gets indexed
• Database location
• CLI Reference
• Troubleshooting
• Development

Demo

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).

1. Ollama installed and running, then pull the default embedding model:

   ollama pull ordis/jina-embeddings-v2-base-code
   

2. One of: Claude Code, Cursor, Codex, or OpenCode

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 manifest
• mcp.json - local lumen MCP server wiring
• hooks/hooks-cursor.json - SessionStart hook
• skills/ - shared doctor and reindex skills

Use 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: