@ory/lumen-opencode 0.0.26

package/.opencode/plugins/lumen.js

@@ -0,0 +1,30 @@
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pluginRoot = path.resolve(__dirname, "../..");
+const runCommand = path.join(
+  pluginRoot,
+  "scripts",
+  process.platform === "win32" ? "run.cmd" : "run.sh",
+);
+
+export const LumenPlugin = async () => {
+  return {
+    config: async (config) => {
+      config.mcp = config.mcp || {};
+      if (!config.mcp.lumen) {
+        config.mcp.lumen = {
+          type: "local",
+          command:
+            process.platform === "win32"
+              ? ["cmd", "/c", runCommand, "stdio"]
+              : ["sh", runCommand, "stdio"],
+          enabled: true,
+        };
+      }
+    },
+  };
+};
+
+export default LumenPlugin;

package/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.0.26"
+}

package/LICENSE

@@ -0,0 +1,179 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submit" means any form of electronic, verbal, or
+      written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of submitting and
+      discussing information to improve the Work, but excluding communication
+      that is conspicuously marked or designated in writing by the copyright
+      owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and included
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by the combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a cross-claim
+      or counterclaim in a lawsuit) alleging that the Work or any patent
+      claim embodied in the Work constitutes direct or contributory patent
+      infringement, then any patent licenses granted to You under this
+      License for that Work shall terminate as of the date such litigation
+      is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+          You may add Your own attribution notices within Derivative
+          Works that You distribute, alongside or in addition to the
+          NOTICE text from the Work, provided that such additional
+          attribution notices cannot be construed as modifying the License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional grant of rights to use, copy, modify, merge,
+      publish, distribute, sublicense, and/or sell copies of the
+      Contribution, either on its own or as part of the Work.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may offer only
+      conditions consistent with this License.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Aeneas Rekkas
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied. See the License for the specific language governing
+   permissions and limitations under the License.

package/README.md

@@ -0,0 +1,422 @@
+![Ory Lumen: Semantic code search for AI agents](.github/lumen-banner.png)
+
+[![CI](https://github.com/ory/lumen/actions/workflows/ci.yml/badge.svg)](https://github.com/ory/lumen/actions/workflows/ci.yml)
+[![Go Report Card](https://goreportcard.com/badge/github.com/ory/lumen)](https://goreportcard.com/report/github.com/ory/lumen)
+[![Go Reference](https://pkg.go.dev/badge/github.com/ory/lumen.svg)](https://pkg.go.dev/github.com/ory/lumen)
+[![Coverage Status](https://coveralls.io/repos/github/ory/lumen/badge.svg?branch=main)](https://coveralls.io/github/ory/lumen?branch=main)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+
+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](https://ollama.com/) or [LM Studio](https://lmstudio.ai/)), SQLite,
+and your CPU. A single static binary and your own local embedding server.
+
+The payoff is measurable and reproducible: across 8 benchmark runs on 8
+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](docs/BENCHMARKS.md) 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           |
+| Patch quality          | **Maintained in all 8 tasks** | —                    |
+
+## Table of contents
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Demo](#demo)
+- [Quick start](#quick-start)
+- [What you get](#what-you-get)
+- [How it works](#how-it-works)
+- [Benchmarks](#benchmarks)
+- [Supported languages](#supported-languages)
+- [Configuration](#configuration)
+  - [Supported embedding models](#supported-embedding-models)
+- [Controlling what gets indexed](#controlling-what-gets-indexed)
+- [Database location](#database-location)
+- [CLI Reference](#cli-reference)
+- [Troubleshooting](#troubleshooting)
+- [Development](#development)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Demo
+
+<img src="docs/demo/demo.gif" alt="Lumen demo" width="600"/>
+
+_Claude Code asking about the
+[Prometheus](https://github.com/prometheus/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](https://github.com/gofrs/flock)).
+
+1. [Ollama](https://ollama.com/) installed and running, then pull the default
+   embedding model:
+   ```bash
+   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 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**
+
+```bash
+/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**
+
+Quick install:
+
+```text
+Fetch and follow instructions from https://raw.githubusercontent.com/ory/lumen/refs/heads/main/.codex/INSTALL.md
+```
+
+Manual install:
+
+```bash
+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.sh" stdio
+```
+
+Detailed docs: [.codex/INSTALL.md](.codex/INSTALL.md)
+
+Verify with:
+
+```bash
+codex mcp get lumen
+ls -la "$HOME/.agents/skills/lumen"
+```
+
+**OpenCode**
+
+Add `@ory/lumen-opencode` to the `plugin` array in your `opencode.json`:
+
+```json
+{
+  "plugin": ["@ory/lumen-opencode"]
+}
+```
+
+Detailed docs: [.opencode/INSTALL.md](.opencode/INSTALL.md)
+
+Verify with:
+
+```bash
+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** - `cd "${CODEX_HOME:-$HOME/.codex}/lumen" && git pull`
+- **OpenCode** - update the version pin in `opencode.json` (e.g.
+  `@ory/lumen-opencode@0.0.27`) 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.
+
+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
+- **11 language families** — Go, Python, TypeScript, JavaScript, Rust, Ruby,
+  Java, PHP, C/C++, C#
+- **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.
+
+```
+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.
+
+## 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** — 8 runs across 8 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%            | -10% (11K → 10K)         | Good (both)    |
+| C++        | **-8%**        | -3%            | +42% (feature task)      | Good (both)    |
+
+**Cost was reduced in every language tested. Quality was maintained in every
+task — zero regressions.** JavaScript and TypeScript show the most dramatic
+efficiency gains: same quality fixes in half the time with two-thirds fewer
+tokens. Even on tasks too hard for either approach (Rust), Lumen cuts the cost
+of failure by 39%.
+
+See [docs/BENCHMARKS.md](docs/BENCHMARKS.md) for all 8 per-language deep dives,
+judge rationales, and reproduce instructions.
+
+## Supported languages
+
+Supports **12 language families** with semantic chunking (9 benchmarked):
+
+| Language         | Parser      | Extensions                                | Benchmark status                              |
+| ---------------- | ----------- | ----------------------------------------- | --------------------------------------------- |
+| Go               | Native AST  | `.go`                                     | Benchmarked: -12% cost, Good quality          |
+| Python           | tree-sitter | `.py`                                     | Benchmarked: Perfect quality, -36% tokens     |
+| TypeScript / TSX | tree-sitter | `.ts`, `.tsx`                             | Benchmarked: -64% tokens, -33% time           |
+| JavaScript / JSX | tree-sitter | `.js`, `.jsx`, `.mjs`                     | Benchmarked: -66% tokens, -53% time           |
+| Dart             | tree-sitter | `.dart`                                   | Benchmarked: -76% cost, -82% tokens, -79% time |
+| Rust             | tree-sitter | `.rs`                                     | Benchmarked: -39% cost, -34% time             |
+| Ruby             | tree-sitter | `.rb`                                     | Benchmarked: -24% cost, -11% time             |
+| PHP              | tree-sitter | `.php`                                    | Benchmarked: -59% tokens, -34% time           |
+| C / C++          | tree-sitter | `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp` | Benchmarked: -8% cost (C++ feature task)      |
+| Java             | tree-sitter | `.java`                                   | Supported                                     |
+| C#               | tree-sitter | `.cs`                                     | Supported                                     |
+
+Go uses the native Go AST parser for the most precise chunks. All other
+languages use tree-sitter grammars. See [docs/BENCHMARKS.md](docs/BENCHMARKS.md)
+for all 9 per-language benchmark deep dives.
+
+## Configuration
+
+All configuration is via environment variables:
+
+| Variable                 | Default                  | Description                                |
+| ------------------------ | ------------------------ | ------------------------------------------ |
+| `LUMEN_EMBED_MODEL`      | see note ¹               | Embedding model (must be in registry)      |
+| `LUMEN_BACKEND`          | `ollama`                 | Embedding backend (`ollama` or `lmstudio`) |
+| `OLLAMA_HOST`            | `http://localhost:11434` | Ollama server URL                          |
+| `LM_STUDIO_HOST`         | `http://localhost:1234`  | LM Studio server URL                       |
+| `LUMEN_MAX_CHUNK_TOKENS` | `512`                    | Max tokens per chunk before splitting      |
+
+¹ `ordis/jina-embeddings-v2-base-code` (Ollama),
+`nomic-ai/nomic-embed-code-GGUF` (LM Studio)
+
+### Supported embedding models
+
+Dimensions and context length are configured automatically per model:
+
+| Model                                | Backend   | Dims | Context | Recommended                                                           |
+| ------------------------------------ | --------- | ---- | ------- | --------------------------------------------------------------------- |
+| `ordis/jina-embeddings-v2-base-code` | Ollama    | 768  | 8192    | **Best default** — lowest cost, no over-retrieval                     |
+| `qwen3-embedding:8b`                 | Ollama    | 4096 | 40960   | **Best quality** — strongest dominance (7/9 wins), very slow indexing |
+| `nomic-ai/nomic-embed-code-GGUF`     | LM Studio | 3584 | 8192    | **Usable** — good quality, but TypeScript over-retrieval raises costs |
+| `qwen3-embedding:4b`                 | Ollama    | 2560 | 40960   | **Not recommended** — highest costs, severe TypeScript over-retrieval |
+| `nomic-embed-text`                   | Ollama    | 768  | 8192    | Untested                                                              |
+| `qwen3-embedding:0.6b`               | Ollama    | 1024 | 32768   | Untested                                                              |
+| `all-minilm`                         | Ollama    | 384  | 512     | Untested                                                              |
+
+Switching models creates a separate index automatically. The model name is part
+of the database path hash, so different models never collide.
+
+## Controlling what gets indexed
+
+Lumen filters files through six layers: built-in directory and lock file skips →
+`.gitignore` → `.lumenignore` → `.gitattributes` (`linguist-generated`) →
+supported file extension. Only files that pass all layers are indexed.
+
+**`.lumenignore`** uses `.gitignore` syntax. Place it in your project root (or
+any subdirectory) to exclude files that aren't in `.gitignore` but are noise for
+code search — generated protobuf files, test snapshots, vendored data, etc.
+
+<details>
+<summary>Built-in skips (always excluded)</summary>
+
+**Directories:** `.git`, `node_modules`, `vendor`, `dist`, `.cache`, `.venv`,
+`venv`, `__pycache__`, `target`, `.gradle`, `_build`, `deps`, `.idea`,
+`.vscode`, `.next`, `.nuxt`, `.build`, `.output`, `bower_components`, `.bundle`,
+`.tox`, `.eggs`, `testdata`, `.hg`, `.svn`
+
+**Lock files:** `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lock`,
+`bun.lockb`, `go.sum`, `composer.lock`, `poetry.lock`, `Pipfile.lock`,
+`Gemfile.lock`, `Cargo.lock`, `pubspec.lock`, `mix.lock`, `flake.lock`,
+`packages.lock.json`
+
+</details>
+
+## Database location
+
+Index databases are stored outside your project:
+
+```
+~/.local/share/lumen/<hash>/index.db
+```
+
+Where `<hash>` is derived from the absolute project path, embedding model name,
+and binary version. Different models or Lumen versions automatically get
+separate indexes. No files are added to your repo, no `.gitignore` modifications
+needed.
+
+You can safely delete the entire `lumen` directory to clear all indexes, or use
+`lumen purge` to do it automatically.
+
+**Git worktrees** are detected automatically. When you create a new worktree
+(`git worktree add` or `claude --worktree`), Lumen finds a sibling worktree's
+existing index and copies it as a seed. The Merkle tree diff then re-indexes
+only the files that actually differ — typically a handful of files instead of
+the entire codebase. No configuration needed; it just works.
+
+## CLI Reference
+
+Download the binary from the
+[GitHub releases page](https://github.com/ory/lumen/releases) or let the plugin
+install it automatically.
+
+```bash
+lumen help
+```
+
+## Troubleshooting
+
+**Ollama not running / "connection refused"**
+
+Start Ollama and verify the model is pulled:
+
+```bash
+ollama serve
+ollama pull ordis/jina-embeddings-v2-base-code
+```
+
+Run `/lumen:doctor` inside Claude Code to confirm connectivity.
+
+In Cursor, Codex, or OpenCode, use the shared `doctor` skill or call
+`health_check` and `index_status` directly.
+
+**Stale index after large refactor**
+
+Run `/lumen:reindex` inside Claude Code to force a full re-index, or:
+
+```bash
+lumen purge && lumen index .
+```
+
+In Codex, use the bundled `reindex` skill to refresh the index through the MCP
+server, or run the same CLI commands for a clean rebuild. The same shared
+`reindex` skill is available in Cursor and OpenCode as well.
+
+**Switching embedding models**
+
+Set `LUMEN_EMBED_MODEL` to a model from the supported table above. Each model
+gets its own database; the old index is not deleted automatically.
+
+**Slow first indexing**
+
+The first run embeds every file. Subsequent runs only process changed files
+(typically a few seconds). For large projects (100k+ lines), first indexing can
+take several minutes — this is a one-time cost.
+
+## Development
+
+```bash
+git clone https://github.com/ory/lumen.git
+cd lumen
+
+# Build locally (CGO required for sqlite-vec)
+make build-local
+
+# Run tests
+make test
+
+# Run linter
+make lint
+
+# Load as a Claude Code plugin from source
+make plugin-dev
+```
+
+See [CLAUDE.md](CLAUDE.md) for architecture details, design decisions, and
+contribution guidelines, and [AGENTS.md](AGENTS.md) for repo-specific agent
+instructions.

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@ory/lumen-opencode",
+  "version": "0.0.26",
+  "description": "Precise local semantic code search plugin for OpenCode — indexes with Go AST/tree-sitter and embeds with Ollama or LM Studio",
+  "type": "module",
+  "main": ".opencode/plugins/lumen.js",
+  "author": "Ory Corp (https://github.com/ory)",
+  "homepage": "https://github.com/ory/lumen",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ory/lumen.git"
+  },
+  "license": "Apache-2.0",
+  "keywords": [
+    "opencode",
+    "semantic-search",
+    "code-index",
+    "mcp",
+    "ollama",
+    "rag"
+  ],
+  "files": [
+    ".opencode/plugins/",
+    ".release-please-manifest.json",
+    "scripts/",
+    "skills/"
+  ]
+}

package/scripts/run.bat

@@ -0,0 +1,60 @@
+@echo off
+setlocal enabledelayedexpansion
+
+:: Determine plugin root: prefer an agent-set env var, then fall back to the
+:: repository layout so the same launcher works across supported hosts.
+if defined CLAUDE_PLUGIN_ROOT (
+  set "PLUGIN_ROOT=%CLAUDE_PLUGIN_ROOT%"
+) else if defined CURSOR_PLUGIN_ROOT (
+  set "PLUGIN_ROOT=%CURSOR_PLUGIN_ROOT%"
+) else (
+  set "PLUGIN_ROOT=%~dp0.."
+)
+
+:: Architecture detection
+set "ARCH=amd64"
+if "%PROCESSOR_ARCHITECTURE%"=="ARM64" set "ARCH=arm64"
+
+:: Environment defaults
+if not defined LUMEN_BACKEND set "LUMEN_BACKEND=ollama"
+if not defined LUMEN_EMBED_MODEL set "LUMEN_EMBED_MODEL=ordis/jina-embeddings-v2-base-code"
+
+:: Binary path
+set "BINARY=%PLUGIN_ROOT%\bin\lumen-windows-%ARCH%.exe"
+
+:: Download on first run if binary is missing
+if not exist "%BINARY%" (
+  set "REPO=ory/lumen"
+
+  :: Always use the version pinned in the manifest — keeps plugin and binary in sync
+  set "MANIFEST=%PLUGIN_ROOT%\.release-please-manifest.json"
+  if not exist "!MANIFEST!" (
+    echo Error: .release-please-manifest.json not found in %PLUGIN_ROOT% >&2
+    exit /b 1
+  )
+  for /f "tokens=*" %%i in ('findstr /r "\"[.]\"" "!MANIFEST!"') do (
+    for /f "tokens=2 delims=:" %%j in ("%%i") do (
+      set "VERSION=v%%~j"
+      set "VERSION=!VERSION: =!"
+      set "VERSION=!VERSION:,=!"
+      set "VERSION=!VERSION:"=!"
+    )
+  )
+
+  if "!VERSION!"=="" (
+    echo Error: could not read version from !MANIFEST! >&2
+    exit /b 1
+  )
+
+  set "ASSET=lumen-!VERSION:~1!-windows-!ARCH!.exe"
+  set "URL=https://github.com/!REPO!/releases/download/!VERSION!/!ASSET!"
+
+  echo Downloading lumen !VERSION! for windows/!ARCH!... >&2
+  if not exist "%PLUGIN_ROOT%\bin" mkdir "%PLUGIN_ROOT%\bin"
+
+  curl -sfL "!URL!" -o "%BINARY%"
+
+  echo Installed lumen to %BINARY% >&2
+)
+
+"%BINARY%" %*

package/scripts/run.cmd

@@ -0,0 +1,11 @@
+#!/usr/bin/env -S 2>/dev/null=2>NUL sh
+@goto batch 2>NUL;rm -f NUL
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+exec "${SCRIPT_DIR}/run.sh" "$@"
+
+:batch
+@echo off
+set "SCRIPT_DIR=%~dp0"
+call "%SCRIPT_DIR%run.bat" %*
+exit /b %ERRORLEVEL%

package/scripts/run.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Determine plugin root: prefer an agent-set env var, then fall back to the
+# repository layout so the same launcher works for Claude, Codex, Cursor,
+# OpenCode, and direct local invocation.
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-$(cd "$(dirname "$0")/.." && pwd)}}"
+
+# Platform detection
+OS="$(uname -s | tr '[:upper:]' '[:lower:]')"
+ARCH="$(uname -m)"
+case "$ARCH" in
+  x86_64)  ARCH="amd64" ;;
+  aarch64) ARCH="arm64" ;;
+esac
+
+# Environment defaults
+export LUMEN_BACKEND="${LUMEN_BACKEND:-ollama}"
+export LUMEN_EMBED_MODEL="${LUMEN_EMBED_MODEL:-ordis/jina-embeddings-v2-base-code}"
+
+# Find binary: check bin/ first, then goreleaser dist/ output, then download
+BINARY=""
+for candidate in \
+  "${PLUGIN_ROOT}/bin/lumen" \
+  "${PLUGIN_ROOT}/bin/lumen-${OS}-${ARCH}"; do
+  if [ -x "$candidate" ]; then
+    BINARY="$candidate"
+    break
+  fi
+done
+
+# Download on first run if no binary found
+if [ -z "$BINARY" ]; then
+  BINARY="${PLUGIN_ROOT}/bin/lumen-${OS}-${ARCH}"
+  REPO="ory/lumen"
+
+  # Always use the version pinned in the manifest — keeps plugin and binary in sync
+  MANIFEST="${PLUGIN_ROOT}/.release-please-manifest.json"
+  if [ ! -f "$MANIFEST" ]; then
+    echo "Error: .release-please-manifest.json not found in ${PLUGIN_ROOT}" >&2
+    exit 1
+  fi
+  VERSION="v$(grep '"[.]"' "$MANIFEST" | sed 's/.*"[^"]*"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/')"
+  if [ -z "$VERSION" ] || [ "$VERSION" = "v" ]; then
+    echo "Error: could not read version from ${MANIFEST}" >&2
+    exit 1
+  fi
+
+  ASSET="lumen-${VERSION#v}-${OS}-${ARCH}"
+  URL="https://github.com/${REPO}/releases/download/${VERSION}/${ASSET}"
+
+  echo "Downloading lumen ${VERSION} for ${OS}/${ARCH}..." >&2
+  mkdir -p "$(dirname "$BINARY")"
+
+  curl -fL --progress-bar --max-time 300 --retry 3 --retry-delay 2 "$URL" -o "$BINARY"
+  chmod +x "$BINARY"
+  echo "Installed lumen to ${BINARY}" >&2
+fi
+
+exec "$BINARY" "$@"

package/scripts/test_run.sh

@@ -0,0 +1,163 @@
+#!/usr/bin/env bash
+# Tests for run.sh URL construction and OS/arch detection logic.
+# Runs entirely offline — no real HTTP calls are made.
+set -euo pipefail
+
+PASS=0
+FAIL=0
+
+ok() {
+  echo "  PASS: $1"
+  PASS=$((PASS + 1))
+}
+
+fail() {
+  echo "  FAIL: $1"
+  echo "        expected: $2"
+  echo "        got:      $3"
+  FAIL=$((FAIL + 1))
+}
+
+assert_eq() {
+  local desc="$1" expected="$2" got="$3"
+  if [ "$expected" = "$got" ]; then
+    ok "$desc"
+  else
+    fail "$desc" "$expected" "$got"
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# asset_name <version_tag> <os> <arch>
+# Mirrors the logic in run.sh: strip leading 'v', build asset filename.
+# ---------------------------------------------------------------------------
+asset_name() {
+  local version="$1" os="$2" arch="$3"
+  local ver_no_v="${version#v}"
+  case "$os" in
+    windows) echo "lumen-${ver_no_v}-${os}-${arch}.exe" ;;
+    *)       echo "lumen-${ver_no_v}-${os}-${arch}" ;;
+  esac
+}
+
+# download_url <repo> <version_tag> <os> <arch>
+download_url() {
+  local repo="$1" version="$2" os="$3" arch="$4"
+  local asset
+  asset="$(asset_name "$version" "$os" "$arch")"
+  echo "https://github.com/${repo}/releases/download/${version}/${asset}"
+}
+
+# ---------------------------------------------------------------------------
+# arch normalisation (mirrors run.sh case statement)
+# ---------------------------------------------------------------------------
+normalise_arch() {
+  case "$1" in
+    x86_64)  echo "amd64" ;;
+    aarch64) echo "arm64" ;;
+    *)       echo "$1" ;;
+  esac
+}
+
+echo "=== asset name tests ==="
+assert_eq "macOS arm64 asset" \
+  "lumen-0.0.1-alpha.4-darwin-arm64" \
+  "$(asset_name "v0.0.1-alpha.4" "darwin" "arm64")"
+
+assert_eq "macOS amd64 asset" \
+  "lumen-0.0.1-alpha.4-darwin-amd64" \
+  "$(asset_name "v0.0.1-alpha.4" "darwin" "amd64")"
+
+assert_eq "Linux amd64 asset" \
+  "lumen-0.0.1-alpha.4-linux-amd64" \
+  "$(asset_name "v0.0.1-alpha.4" "linux" "amd64")"
+
+assert_eq "Linux arm64 asset" \
+  "lumen-0.0.1-alpha.4-linux-arm64" \
+  "$(asset_name "v0.0.1-alpha.4" "linux" "arm64")"
+
+assert_eq "Windows amd64 asset (.exe)" \
+  "lumen-0.0.1-alpha.4-windows-amd64.exe" \
+  "$(asset_name "v0.0.1-alpha.4" "windows" "amd64")"
+
+echo ""
+echo "=== download URL tests ==="
+REPO="ory/lumen"
+VERSION="v0.0.1-alpha.4"
+
+assert_eq "macOS arm64 URL" \
+  "https://github.com/ory/lumen/releases/download/v0.0.1-alpha.4/lumen-0.0.1-alpha.4-darwin-arm64" \
+  "$(download_url "$REPO" "$VERSION" "darwin" "arm64")"
+
+assert_eq "Linux amd64 URL" \
+  "https://github.com/ory/lumen/releases/download/v0.0.1-alpha.4/lumen-0.0.1-alpha.4-linux-amd64" \
+  "$(download_url "$REPO" "$VERSION" "linux" "amd64")"
+
+assert_eq "Windows amd64 URL" \
+  "https://github.com/ory/lumen/releases/download/v0.0.1-alpha.4/lumen-0.0.1-alpha.4-windows-amd64.exe" \
+  "$(download_url "$REPO" "$VERSION" "windows" "amd64")"
+
+echo ""
+echo "=== arch normalisation tests ==="
+assert_eq "x86_64 → amd64"  "amd64" "$(normalise_arch "x86_64")"
+assert_eq "aarch64 → arm64" "arm64" "$(normalise_arch "aarch64")"
+assert_eq "arm64 passthrough" "arm64" "$(normalise_arch "arm64")"
+assert_eq "amd64 passthrough" "amd64" "$(normalise_arch "amd64")"
+
+echo ""
+echo "=== binary candidate priority tests ==="
+TMP_DIR="$(mktemp -d)"
+trap 'rm -rf "$TMP_DIR"' EXIT
+
+BIN_DIR="${TMP_DIR}/bin"
+mkdir -p "$BIN_DIR"
+
+# Simulate: only downloaded binary present → should pick lumen-os-arch
+touch "${BIN_DIR}/lumen-linux-amd64"
+chmod +x "${BIN_DIR}/lumen-linux-amd64"
+
+FOUND=""
+for candidate in "${BIN_DIR}/lumen" "${BIN_DIR}/lumen-linux-amd64"; do
+  if [ -x "$candidate" ]; then FOUND="$candidate"; break; fi
+done
+assert_eq "picks lumen-linux-amd64 when lumen absent" \
+  "${BIN_DIR}/lumen-linux-amd64" "$FOUND"
+
+# Simulate: both present → local dev build wins
+touch "${BIN_DIR}/lumen"
+chmod +x "${BIN_DIR}/lumen"
+
+FOUND=""
+for candidate in "${BIN_DIR}/lumen" "${BIN_DIR}/lumen-linux-amd64"; do
+  if [ -x "$candidate" ]; then FOUND="$candidate"; break; fi
+done
+assert_eq "prefers bin/lumen (dev build) over downloaded binary" \
+  "${BIN_DIR}/lumen" "$FOUND"
+
+echo ""
+echo "=== version resolution tests ==="
+TMP_MANIFEST_DIR="$(mktemp -d)"
+trap 'rm -rf "$TMP_MANIFEST_DIR" "$TMP_DIR"' EXIT
+
+MANIFEST="${TMP_MANIFEST_DIR}/.release-please-manifest.json"
+printf '{\n  ".": "1.2.3"\n}\n' > "$MANIFEST"
+
+resolved_version_from_manifest() {
+  local manifest="$1"
+  local ver="v$(grep '"[.]"' "$manifest" | sed 's/.*"[^"]*"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/')"
+  echo "$ver"
+}
+
+assert_eq "manifest version resolution" \
+  "v1.2.3" \
+  "$(resolved_version_from_manifest "$MANIFEST")"
+
+assert_eq "pre-release version preserved" \
+  "v0.0.1-alpha.4" \
+  "$(printf '{\n  ".": "0.0.1-alpha.4"\n}\n' | grep '"[.]"' | sed 's/.*"[^"]*"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/v\1/')"
+
+echo ""
+echo "=== summary ==="
+echo "  passed: $PASS"
+echo "  failed: $FAIL"
+[ "$FAIL" -eq 0 ] || exit 1

package/scripts/test_run_cmd.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+TMP_DIR="$(mktemp -d)"
+trap 'rm -rf "$TMP_DIR"' EXIT
+
+cp "${SCRIPT_DIR}/run.cmd" "${TMP_DIR}/run.cmd"
+chmod +x "${TMP_DIR}/run.cmd"
+
+cat > "${TMP_DIR}/run.sh" <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+printf 'delegated:%s\n' "$*"
+EOF
+chmod +x "${TMP_DIR}/run.sh"
+
+OUTPUT="$("${TMP_DIR}/run.cmd" stdio --flag)"
+EXPECTED="delegated:stdio --flag"
+
+if [ "$OUTPUT" != "$EXPECTED" ]; then
+  echo "FAIL: run.cmd should delegate to run.sh when exec'd directly on Unix"
+  echo "expected: $EXPECTED"
+  echo "got:      $OUTPUT"
+  exit 1
+fi
+
+echo "PASS: run.cmd delegates to run.sh when exec'd directly on Unix"

package/skills/doctor/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: doctor
+description: Run a health check on the bundled Lumen semantic search setup for the current project, verify backend reachability and index freshness, and summarize remediation steps.
+---
+
+# Lumen Doctor
+
+Run a health check on the bundled Lumen semantic search setup for the current
+project.
+
+## Steps
+
+1. Call the Lumen `health_check` tool to verify the embedding service is
+   reachable.
+2. Call the Lumen `index_status` tool with `path` or `cwd` set to the current
+   working directory to check index freshness.
+3. Report a concise summary:
+   - Embedding service status, backend, host, and model
+   - Index totals: files, chunks, last indexed time, stale or fresh
+   - Any MCP or plugin setup issue that blocks the tools
+4. If no index exists yet, explain that the Lumen `semantic_search` tool seeds
+   the index on first use.
+5. If the user wants eager indexing instead of waiting for the next search,
+   suggest running `lumen index .` in the repository root.

package/skills/reindex/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: reindex
+description: Refresh or rebuild the bundled Lumen index for the current project, preferring MCP-driven refreshes and using the CLI only for an explicit clean rebuild.
+---
+
+# Lumen Reindex
+
+Refresh or rebuild the bundled Lumen index for the current project.
+
+## Steps
+
+1. Call the Lumen `index_status` tool for the current working directory so you
+   can report the current state before making changes.
+2. If the user wants the index refreshed or seeded, call the Lumen
+   `semantic_search` tool with a broad natural-language query and set `path` or
+   `cwd` to the current working directory. The search tool refreshes stale or
+   missing indexes automatically.
+3. If the user explicitly asks for a clean rebuild, explain that
+   `lumen purge && lumen index .` deletes cached indexes before rebuilding,
+   then run it via the shell.
+4. After the refresh or rebuild, report the new index status.