Skip to content
Back to search

lumen

Save 30% token costs when using Claude Code, Codex, OpenCode for free - with open source, local semantic search. Works for small and large codebases and monorepos! Enterprise-ready and fully compliant via Ollama and SQLite-vec.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ory--lumen/badge.svg)](/listings/ory--lumen)

HTML

<a href="/listings/ory--lumen"><img src="/api/listings/ory--lumen/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**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](https://github.com/gofrs/flock)).

1. [Ollama](https://ollama.com/) installed and running, then pull the default embedding model:

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

2. One of: [Claude Code](https://code.claude.com/docs/en/quickstart), [Cursor](https://cursor.com/), [Codex](https://developers.openai.com/codex/cli), or [OpenCode](https://opencode.ai/)

**Note:** Installation differs by platform. Claude Code and Codex install from plugin marketplaces. 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](.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**

Codex CLI 0.147.0 or newer installs Lumen as a native plugin:

codex plugin marketplace add ory/claude-plugins
codex plugin add lumen@ory

If the marketplace already exists, run `codex plugin marketplace upgrade ory` before installing. Legacy manual-clone and broken-plugin repair instructions: [.codex/INSTALL.md](.codex/INSTALL.md).

Verify with:

codex mcp get lumen --json

**OpenCode**

Add `@ory/lumen-opencode` to the `plugin` array in your `opencode.json`:

{
  "plugin": ["@ory/lumen-opencode"]
}

Detailed docs: [.opencode/INSTALL.md](.opencode/INSTALL.md)

Verify with:

opencode mcp list

**Updating**

- **Claude Code** - update through Claude's plugin marketplace - **Cursor** - refresh or reinstall the bundled plugin through Cursor after updating this repository or the published package - **Codex** - upgrade the `ory` marketplace, reinstall `lumen@ory`, and restart - **OpenCode** - update the version pin in `opencode.json` (e.g. `@ory/lumen-opencode@0.0.29`) and restart OpenCode

On first Claude Code or Cursor session start, Lumen:

1. Downloads the binary automatically from the [latest GitHub release](https://github.com/ory/lumen/releases) 2. Indexes your project in the background using Merkle tree change detection 3. 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. Codex stores the downloaded binary in the plugin's writable data directory rather than the read-only package cache.

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 was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 514 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ![Ory Lumen: Semantic code search for AI agents](.github/lumen-banner.png)
  2. [![CI](https://github.com/ory/lumen/actions/workflows/ci.yml/badge.svg)](https://github.com/ory/lumen/actions/workflows/ci.yml)
  3. [![Go Report Card](https://goreportcard.com/badge/github.com/ory/lumen)](https://goreportcard.com/report/github.com/ory/lumen)
  4. [![Go Reference](https://pkg.go.dev/badge/github.com/ory/lumen.svg)](https://pkg.go.dev/github.com/ory/lumen)
  5. [![Coverage Status](https://coveralls.io/repos/github/ory/lumen/badge.svg?branch=main)](https://coveralls.io/github/ory/lumen?branch=main)
  6. [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
  7. Claude reads entire files to find what it needs. Lumen gives it a map.
  8. Lumen is a 100% local semantic code search engine for AI coding agents. No API
  9. keys, no cloud, no external database, just open-source embedding models
  10. ([Ollama](https://ollama.com/) or [LM Studio](https://lmstudio.ai/)), SQLite,
  11. and your CPU. A single static binary and your own local embedding server.
  12. The payoff is measurable and reproducible: across 9 benchmark runs on 9
  13. languages and real GitHub bug-fix tasks, Lumen cuts cost in **every single
  14. language** — up to 39%. Output tokens drop by up to 66%, sessions complete up to
  15. 53% faster, and patch quality is maintained in every task. All verified with a
  16. [transparent, open-source benchmark framework](docs/BENCHMARKS.md) that you can
  17. run yourself.
  18. | | With Lumen | Baseline (no Lumen) |
  19. | ---------------------- | ----------------------------- | -------------------- |
  20. | Cost (avg, bug-fix) | **$0.29** (-26%) | $0.40 |
  21. | Time (avg, bug-fix) | **125s** (-28%) | 174s |
  22. | Output tokens (avg) | **5,247** (-37%) | 8,323 |
  23. | JavaScript (marked) | **$0.32, 119s** (-33%, -53%) | $0.48, 255s |
  24. | Rust (toml) | **$0.38, 204s** (-39%, -34%) | $0.61, 310s |
  25. | PHP (monolog) | **$0.14, 34s** (-27%, -34%) | $0.19, 52s |
  26. | TypeScript (commander) | **$0.14, 56s** (-27%, -33%) | $0.19, 84s |
  27. | Svelte (chat-ui) | **$0.10, 56s** (-26%, -31%) | $0.14, 80s |
  28. | Patch quality | **Maintained in all 9 tasks** | — |
  29. ## Table of contents
  30. <!-- START doctoc generated TOC please keep comment here to allow auto update -->
  31. <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
  32. - [Demo](#demo)
  33. - [Quick start](#quick-start)
  34. - [What you get](#what-you-get)
  35. - [How it works](#how-it-works)
  36. - [Benchmarks](#benchmarks)
  37. - [Supported languages](#supported-languages)
  38. - [Configuration](#configuration)
  39. - [Supported embedding models](#supported-embedding-models)
  40. - [Controlling what gets indexed](#controlling-what-gets-indexed)
  41. - [Database location](#database-location)
  42. - [CLI Reference](#cli-reference)
  43. - [Troubleshooting](#troubleshooting)
  44. - [Development](#development)
  45. <!-- END doctoc generated TOC please keep comment here to allow auto update -->
  46. ## Demo
  47. <img src="docs/demo/demo.gif" alt="Lumen demo" width="600"/>
  48. _Claude Code asking about the
  49. [Prometheus](https://github.com/prometheus/prometheus) codebase. Lumen's
  50. `semantic_search` finds the relevant code without reading entire files._
  51. ## Quick start
  52. **Prerequisites:**
  53. > **Platform support:** Linux, macOS, and Windows. File locking for background
  54. > indexing coordination uses `flock(2)` on Unix and `LockFileEx` on Windows
  55. > (via [gofrs/flock](https://github.com/gofrs/flock)).
  56. 1. [Ollama](https://ollama.com/) installed and running, then pull the default
  57. embedding model:
  58. ```bash
  59. ollama pull ordis/jina-embeddings-v2-base-code
  60. ```
  61. 2. One of:
  62. [Claude Code](https://code.claude.com/docs/en/quickstart),
  63. [Cursor](https://cursor.com/),
  64. [Codex](https://developers.openai.com/codex/cli), or
  65. [OpenCode](https://opencode.ai/)
  66. **Note:** Installation differs by platform. Claude Code and Codex install from
  67. plugin marketplaces. OpenCode installs from npm. Cursor packaging is shipped
  68. in this repository and is ready for Cursor's plugin distribution workflow.
  69. **Install:**
  70. **Claude Code**
  71. ```bash
  72. /plugin marketplace add ory/claude-plugins
  73. /plugin install lumen@ory
  74. ```
  75. Verify by starting a new Claude session and running `/lumen:doctor`.
  76. **Cursor**
  77. Lumen ships a native Cursor plugin bundle in this repository:
  78. - `.cursor-plugin/plugin.json` - plugin manifest
  79. - `mcp.json` - local `lumen` MCP server wiring
  80. - `hooks/hooks-cursor.json` - SessionStart hook
  81. - `skills/` - shared `doctor` and `reindex` skills
  82. Use Cursor's plugin installation or distribution workflow with this bundle.
  83. Detailed packaging notes: [.cursor-plugin/INSTALL.md](.cursor-plugin/INSTALL.md)
  84. Verify by opening a new Cursor agent session and asking it to use the `doctor`
  85. skill or the Lumen `semantic_search` tool.
  86. **Codex**
  87. Codex CLI 0.147.0 or newer installs Lumen as a native plugin:
  88. ```bash
  89. codex plugin marketplace add ory/claude-plugins
  90. codex plugin add lumen@ory
  91. ```
  92. If the marketplace already exists, run `codex plugin marketplace upgrade ory`
  93. before installing. Legacy manual-clone and broken-plugin repair instructions:
  94. [.codex/INSTALL.md](.codex/INSTALL.md).
  95. Verify with:
  96. ```bash
  97. codex mcp get lumen --json
  98. ```
  99. **OpenCode**
  100. Add `@ory/lumen-opencode` to the `plugin` array in your `opencode.json`:
  101. ```json
  102. {
  103. "plugin": ["@ory/lumen-opencode"]
  104. }
  105. ```
  106. Detailed docs: [.opencode/INSTALL.md](.opencode/INSTALL.md)
  107. Verify with:
  108. ```bash
  109. opencode mcp list
  110. ```
  111. **Updating**
  112. - **Claude Code** - update through Claude's plugin marketplace
  113. - **Cursor** - refresh or reinstall the bundled plugin through Cursor after
  114. updating this repository or the published package
  115. - **Codex** - upgrade the `ory` marketplace, reinstall `lumen@ory`, and restart
  116. - **OpenCode** - update the version pin in `opencode.json` (e.g.
  117. `@ory/lumen-opencode@0.0.29`) and restart OpenCode
  118. On first Claude Code or Cursor session start, Lumen:
  119. 1. Downloads the binary automatically from the
  120. [latest GitHub release](https://github.com/ory/lumen/releases)
  121. 2. Indexes your project in the background using Merkle tree change detection
  122. 3. Registers a `semantic_search` MCP tool that the host can use automatically
  123. In Codex and OpenCode, the same binary download and index seeding happen on the
  124. first `semantic_search` call. Codex stores the downloaded binary in the
  125. plugin's writable data directory rather than the read-only package cache.
  126. Two shared skills are also available: `doctor` (health check) and `reindex`
  127. (forced re-indexing). Claude exposes them as `/lumen:doctor` and
  128. `/lumen:reindex`; the other hosts discover the same shared skill content
  129. through their native skill systems.
  130. The same `semantic_search`, `health_check`, and `index_status` MCP tools plus
  131. the shared `doctor` and `reindex` skills are exposed through the Codex,
  132. Cursor, and OpenCode surfaces as well. The first `semantic_search` call seeds
  133. or refreshes the index automatically.
  134. ## What you get
  135. - **Semantic vector search** — Claude finds relevant functions, types, and
  136. modules by meaning, not keyword matching
  137. - **Auto-indexing** — indexes on session start, only re-processes changed files
  138. via Merkle tree diffing
  139. - **Incremental updates** — re-indexes only what changed; large codebases
  140. re-index in seconds after the first run
  141. - **12 language families** — Go, Python, TypeScript, JavaScript, Svelte, Rust,
  142. Ruby, Java, PHP, C/C++, C#, Dart
  143. - **Git worktree support** — worktrees share index data automatically; a new
  144. worktree seeds from a sibling's index and only re-indexes changed files,
  145. turning minutes of embedding into seconds
  146. - **Zero cloud** — embeddings stay on your machine; no data leaves your network
  147. - **Ollama and LM Studio** — works with either local embedding backend
  148. ## How it works
  149. Lumen sits between your codebase and Claude as an MCP server. When a session
  150. starts, it walks your project and builds a **Merkle tree** over file hashes:
  151. only changed files get re-chunked and re-embedded. Each file is split into
  152. semantic chunks (functions, types, methods) using Go's native AST or tree-sitter
  153. grammars for other languages. Chunks are embedded and stored in **SQLite +
  154. sqlite-vec** using cosine-distance KNN for retrieval.
  155. ```
  156. Files → semantic chunks → vector embeddings → SQLite/sqlite-vec → KNN search
  157. ```
  158. When Claude needs to understand code, it calls `semantic_search` instead of
  159. reading entire files. The index is stored outside your repo
  160. (`~/.local/share/lumen/<hash>/index.db`). Git worktrees from the same repository
  161. use one collection for a compatible model, vector-storage, and chunking profile;
  162. non-Git projects use private collections. Different profiles never collide.
  163. ## Benchmarks
  164. Lumen is evaluated using **bench-swe**: a SWE-bench-style harness that runs
  165. Claude on real GitHub bug-fix tasks and measures cost, time, output tokens, and
  166. patch quality — with and without Lumen. All results are reproducible: raw JSONL
  167. streams, patch diffs, and judge ratings are committed to this repository.
  168. **Key results** — 9 runs across 9 languages, hard difficulty, real GitHub
  169. issues (`ordis/jina-embeddings-v2-base-code`, Ollama):
  170. | Language | Cost Reduction | Time Reduction | Output Token Reduction | Quality |
  171. | ---------- | -------------- | -------------- | ----------------------- | -------------- |
  172. | Rust | **-39%** | **-34%** | **-31%** (18K → 12K) | Poor (both) |
  173. | JavaScript | **-33%** | **-53%** | **-66%** (14K → 5K) | Perfect (both) |
  174. | TypeScript | **-27%** | **-33%** | **-64%** (5K → 1.8K) | Good (both) |
  175. | PHP | **-27%** | **-34%** | **-59%** (1.9K → 0.8K) | Good (both) |
  176. | Ruby | **-24%** | **-11%** | -9% (6.1K → 5.6K) | Good (both) |
  177. | Python | **-20%** | **-29%** | **-36%** (1.7K → 1.1K) | Perfect (both) |
  178. | Go | **-12%** | -9% | -10% (11K → 10K) | Good (both) |
  179. | C++ | **-8%** | -3% | +42% (feature task) | Good (both) |
  180. | Svelte | **-26%** | **-31%** | **-26%** (4.0K → 3.0K) | Poor (both) |
  181. **Cost was reduced in every language tested. Quality was maintained in every
  182. task — zero regressions.** JavaScript and TypeScript show the most dramatic
  183. efficiency gains: same quality fixes in half the time with two-thirds fewer
  184. tokens. Even on tasks too hard for either approach (Rust, Svelte), Lumen cuts
  185. the cost of failure by 26–39%.
  186. See [docs/BENCHMARKS.md](docs/BENCHMARKS.md) for all 9 per-language deep dives,
  187. judge rationales, and reproduce instructions.
  188. ## Supported languages
  189. Supports **12 language families** with semantic chunking (10 benchmarked):
  190. | Language | Parser | Extensions | Benchmark status |
  191. | ---------------- | ----------- | ----------------------------------------- | --------------------------------------------- |
  192. | Go | Native AST | `.go` | Benchmarked: -12% cost, Good quality |
  193. | Python | tree-sitter | `.py` | Benchmarked: Perfect quality, -36% tokens |
  194. | TypeScript / TSX | tree-sitter | `.ts`, `.tsx` | Benchmarked: -64% tokens, -33% time |
  195. | JavaScript / JSX | tree-sitter | `.js`, `.jsx`, `.mjs` | Benchmarked: -66% tokens, -53% time |
  196. | Dart | tree-sitter | `.dart` | Benchmarked: -76% cost, -82% tokens, -79% time |
  197. | Rust | tree-sitter | `.rs` | Benchmarked: -39% cost, -34% time |
  198. | Ruby | tree-sitter | `.rb` | Benchmarked: -24% cost, -11% time |
  199. | PHP | tree-sitter | `.php` | Benchmarked: -59% tokens, -34% time |
  200. | C / C++ | tree-sitter | `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp` | Benchmarked: -8% cost (C++ feature task) |
  201. | Svelte | tree-sitter | `.svelte` | Benchmarked: -26% cost, -31% time |
  202. | Java | tree-sitter | `.java` | Supported |
  203. | C# | tree-sitter | `.cs` | Supported |
  204. Go uses the native Go AST parser for the most precise chunks. All other
  205. languages use tree-sitter grammars. See [docs/BENCHMARKS.md](docs/BENCHMARKS.md)
  206. for all 10 per-language benchmark deep dives.
  207. ## Configuration
  208. All configuration is via environment variables:
  209. | Variable | Default | Description |
  210. | ------------------------ | ------------------------ | ------------------------------------------------------------- |
  211. | `LUMEN_EMBED_MODEL` | see note ¹ | Embedding model; use with `LUMEN_EMBED_DIMS` for unlisted models |
  212. | `LUMEN_BACKEND` | `ollama` | Embedding backend (`ollama` or `lmstudio`) |
  213. | `OLLAMA_HOST` | `http://localhost:11434` | Ollama server URL |
  214. | `LM_STUDIO_HOST` | `http://localhost:1234` | LM Studio server URL |
  215. | `LUMEN_MAX_CHUNK_TOKENS` | `512` | Max tokens per chunk before splitting |
  216. | `LUMEN_VECTOR_STORAGE` | `int8` | Vector precision (`int8` or `float32`) |
  217. | `LUMEN_EMBED_DIMS` | — | Override embedding dimensions (required for unlisted models) |
  218. | `LUMEN_EMBED_CTX` | `8192` (unlisted models) | Override context window length |
  219. ¹ `ordis/jina-embeddings-v2-base-code` (Ollama),
  220. `nomic-ai/nomic-embed-code-GGUF` (LM Studio)
  221. ### Supported embedding models
  222. Dimensions and context length are configured automatically per model:
  223. | Model | Backend | Dims | Context | Recommended |
  224. | ------------------------------------ | --------- | ---- | ------- | --------------------------------------------------------------------- |
  225. | `ordis/jina-embeddings-v2-base-code` | Ollama | 768 | 8192 | **Best default** — lowest cost, no over-retrieval |
  226. | `qwen3-embedding:8b` | Ollama | 4096 | 40960 | **Best quality** — strongest dominance (7/9 wins), very slow indexing |
  227. | `nomic-ai/nomic-embed-code-GGUF` | LM Studio | 3584 | 8192 | **Usable** — good quality, but TypeScript over-retrieval raises costs |
  228. | `qwen3-embedding:4b` | Ollama | 2560 | 40960 | **Not recommended** — highest costs, severe TypeScript over-retrieval |
  229. | `nomic-embed-text` | Ollama | 768 | 8192 | Untested |
  230. | `qwen3-embedding:0.6b` | Ollama | 1024 | 32768 | Untested |
  231. | `all-minilm` | Ollama | 384 | 512 | Untested |
  232. Switching models creates a separate index automatically. The model name is part
  233. of the database path hash, so different models never collide.
  234. > **Caveat**: the DB path hash includes the model name but not the backend. If
  235. > the same model name is configured on two backends (e.g. an Ollama and an LM
  236. > Studio entry both named `foo`), they share the same index — use distinct
  237. > model names per backend to avoid collisions.
  238. ### Selecting a server per invocation
  239. `lumen index` and `lumen search` accept `--model`/`-m` and `--backend`/`-b`
  240. to pick from a multi-server `config.yaml`. The selection filters the
  241. configured servers to those matching both fields; failover still works
  242. within the filtered subset.
  243. ```sh
  244. # Index with the Ollama server matching this model name.
  245. lumen index --model ordis/jina-embeddings-v2-base-code .
  246. # Same model name hosted on LM Studio (present in YAML, not in the
  247. # static registry) — accepted because the name is configured.
  248. lumen index --model text-embedding-jina-embeddings-v2-base-code .
  249. # Disambiguate when the same model is configured on two backends.
  250. lumen index --model my-embed --backend lmstudio .
  251. # Pick the first configured Ollama server regardless of model.
  252. lumen search --backend ollama "…"
  253. ```
  254. If `--model` is not configured in YAML but is a known registry model (and
  255. `--backend` is unset), Lumen falls back to mutating the default server's
  256. model — preserving `lumen index --model all-minilm .` for users with no YAML.
  257. ### Using a custom or unlisted model
  258. If your model is not in the registry above, set `LUMEN_EMBED_DIMS` to bypass the
  259. registry check. `LUMEN_EMBED_CTX` is optional and defaults to `8192`.
  260. Both variables can also override values for _known_ models — useful when running
  261. a model variant with a longer context window or different output dimensions.
  262. ```sh
  263. LUMEN_BACKEND=lmstudio
  264. LM_STUDIO_HOST=http://localhost:8801
  265. LUMEN_EMBED_MODEL=mlx-community/Qwen3-Embedding-8B-4bit-DWQ
  266. LUMEN_EMBED_DIMS=4096
  267. LUMEN_EMBED_CTX=40960 # optional, defaults to 8192
  268. ```
  269. ## Controlling what gets indexed
  270. Lumen filters files through six layers: built-in directory and lock file skips →
  271. `.gitignore` → `.lumenignore` → `.gitattributes` (`linguist-generated`) →
  272. supported file extension. Only files that pass all layers are indexed.
  273. **`.lumenignore`** uses `.gitignore` syntax. Place it in your project root (or
  274. any subdirectory) to exclude files that aren't in `.gitignore` but are noise for
  275. code search — generated protobuf files, test snapshots, vendored data, etc.
  276. <details>
  277. <summary>Built-in skips (always excluded)</summary>
  278. **Directories:** `.git`, `node_modules`, `vendor`, `dist`, `.cache`, `.venv`,
  279. `venv`, `__pycache__`, `target`, `.gradle`, `_build`, `deps`, `.idea`,
  280. `.vscode`, `.next`, `.nuxt`, `.build`, `.output`, `bower_components`, `.bundle`,
  281. `.tox`, `.eggs`, `testdata`, `.hg`, `.svn`
  282. **Lock files:** `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lock`,
  283. `bun.lockb`, `go.sum`, `composer.lock`, `poetry.lock`, `Pipfile.lock`,
  284. `Gemfile.lock`, `Cargo.lock`, `pubspec.lock`, `mix.lock`, `flake.lock`,
  285. `packages.lock.json`
  286. </details>
  287. ## Database location
  288. Index databases are stored outside your project:
  289. ```
  290. ~/.local/share/lumen/<hash>/index.db
  291. ```
  292. Where `<hash>` identifies the Git common directory (or the absolute path for a
  293. non-Git project), indexed scope, embedding model and dimensions, vector
  294. precision, chunking profile, and index version. Worktrees in one repository
  295. share content-addressed file revisions and vectors while retaining independent
  296. project memberships. Vectors use int8 storage by default; set
  297. `LUMEN_VECTOR_STORAGE=float32` to opt out. No files are added to your repo.
  298. You can safely delete the entire `lumen` directory to clear all indexes, or let
  299. Lumen reclaim the space for you:
  300. ```bash
  301. lumen clean # remove indexes unused for 30 days or whose project is gone
  302. lumen clean --days 7 # tighten the cutoff to a week
  303. lumen clean --days 0 # remove every eligible index except actively locked indexes
  304. ```
  305. An index counts as used every time Lumen opens it (search, indexing, status, or
  306. session start), so indexes for projects you still work on are never removed.
  307. Indexes with an indexer currently running are always kept.
  308. **Git worktrees** are detected automatically. A new worktree attaches unchanged
  309. path-and-content revisions directly from the repository collection and embeds
  310. only missing chunk inputs. Removing an old worktree drops its memberships;
  311. shared revisions and vectors remain until their final reference disappears.
  312. Legacy per-worktree indexes migrate lazily, reusing unchanged float32 vectors
  313. without contacting the embedding backend.
  314. For the complete storage key, sharing rules, status metrics, migration process,
  315. and cleanup lifecycle, see [Index storage and lifecycle](docs/INDEX_STORAGE.md).
  316. ## CLI Reference
  317. Download the binary from the
  318. [GitHub releases page](https://github.com/ory/lumen/releases) or let the plugin
  319. install it automatically.
  320. ```bash
  321. lumen help
  322. ```
  323. ## Troubleshooting
  324. **Ollama not running / "connection refused"**
  325. Start Ollama and verify the model is pulled:
  326. ```bash
  327. ollama serve
  328. ollama pull ordis/jina-embeddings-v2-base-code
  329. ```
  330. Run `/lumen:doctor` inside Claude Code to confirm connectivity.
  331. In Cursor, Codex, or OpenCode, use the shared `doctor` skill or call
  332. `health_check` and `index_status` directly.
  333. **Stale index after large refactor**
  334. Run `/lumen:reindex` inside Claude Code to force a full re-index, or:
  335. ```bash
  336. lumen index --force .
  337. ```
  338. In Codex, use the bundled `reindex` skill to refresh the index through the MCP
  339. server, or run the same CLI commands for a clean rebuild. The same shared
  340. `reindex` skill is available in Cursor and OpenCode as well.
  341. **LM Studio: embedding model appears under LLMs instead of Embeddings**
  342. LM Studio classifies embedding models by matching the GGUF `arch` field against
  343. a hardcoded allowlist (`bert`, `nomic-bert`). Models built on other
  344. architectures — including Qwen2-based models like `nomic-embed-code` — are
  345. misclassified as LLMs. This affects `lms ls` output and the `/v1/embeddings`
  346. REST endpoint.
  347. **Fix (GGUF, v0.3.16+):** Open LM Studio → My Models, click the gear icon next
  348. to the model, set **Override Domain Type** → **Text Embedding**.
  349. > **macOS / Apple Silicon:** MLX format models are significantly faster on Apple
  350. > Silicon. However, LM Studio removed the domain type override for MLX in
  351. > v0.3.30+, so MLX embedding models cannot be reclassified. Use the GGUF
  352. > variant to retain the override option, or switch to Ollama
  353. > (`ordis/jina-embeddings-v2-base-code` or `qwen3-embedding:8b`).
  354. **Switching embedding models**
  355. Set `LUMEN_EMBED_MODEL` to a model from the supported table above. Each model
  356. gets its own database; the old index is not deleted automatically.
  357. Changing `LUMEN_VECTOR_STORAGE`, `LUMEN_EMBED_DIMS`, or `LUMEN_MAX_CHUNK_TOKENS`
  358. also selects a separate collection. Run `lumen clean` after the old profile is
  359. no longer in use if you want to reclaim its disk space.
  360. **Understanding index size and deduplication**
  361. Call `index_status` for the project. It reports project-local file and chunk
  362. counts alongside collection-wide unique vectors, shared references,
  363. deduplication ratio, vector precision, database size, and currently reclaimable
  364. SQLite pages. See
  365. [Index storage and lifecycle](docs/INDEX_STORAGE.md#reading-index-status) for
  366. definitions and examples.
  367. **Slow first indexing**
  368. The first run embeds every file. Subsequent runs only process changed files
  369. (typically a few seconds). For large projects (100k+ lines), first indexing can
  370. take several minutes — this is a one-time cost.
  371. ## Development
  372. ```bash
  373. git clone https://github.com/ory/lumen.git
  374. cd lumen
  375. # Build locally (CGO required for sqlite-vec)
  376. make build-local
  377. # Run tests
  378. make test
  379. # Run linter
  380. make lint
  381. # Load as a Claude Code plugin from source
  382. make plugin-dev
  383. ```
  384. See [CLAUDE.md](CLAUDE.md) for architecture details, design decisions, and
  385. contribution guidelines, and [AGENTS.md](AGENTS.md) for repo-specific agent
  386. instructions.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.