Content
# OpenCodeRAG
OpenCodeRAG is a **local-first RAG plugin** for semantic code and image search, with a built-in **local decision model** for fast classification. It converts your codebase into vector indices and retrieves relevant code chunks on natural language queries. The primary aim is to save tokens by replacing full-file reads with targeted chunk retrieval and to speed-up tool calls for large codebases. Integrates seamlessly with [OpenCode](https://opencode.ai) and works as a standalone MCP server or CLI tool for other AI harnesses.
You don't need a dedicated GPU to run smaller embedding LLMs, as these models can still run performant on modern CPUs.
[](https://www.npmjs.com/package/opencode-rag-plugin)
> ⚠️ **Note:** Don't confuse this with the npm package `opencode-rag` (a discontinued project by a different author).
## Quick Start
```bash
# 1. Install globally (automatically sets up the OpenCode runtime)
npm install -g opencode-rag-plugin
# 2. One command per workspace - runtime check + workspace setup
cd /path/to/your/project
opencode-rag setup
# 3. Index your workspace
opencode-rag index
# 4. CLI search test
opencode-rag query "authentication middleware"
```
`opencode-rag setup` installs/verifies the machine-level runtime and, when
run inside a project, initializes the workspace (`.opencode/`, plugin entries,
skill file, `opencode-rag.json`) in one step. When the installed version is
outdated, it fetches and installs the latest published version from npm.
`opencode-rag init` remains available for re-syncing an already initialized
workspace, and `opencode-rag update` upgrades to a newer release.
**Prerequisites:** Node.js v22+, [Ollama](https://ollama.ai) (default) or other LLM-hosters (OpenAI-, Google- or Anthropic-compatible).
`pnpm add -g opencode-rag-plugin`, `yarn global add opencode-rag-plugin`, and `bun add -g opencode-rag-plugin` work as drop-in replacements for the global install — setup and update detect the package manager that owns the install and never require npm on `PATH`.
> **Contributors / developers:** Clone the repo and use `npm install --legacy-peer-deps; npm run build` — see [Development docs](doc/development.md).
## Key Features
| Feature | Description |
|---|---|
| **MCP server** | `opencode-rag mcp` - stdio-based MCP server exposing `search_semantic`, `get_file_skeleton`, `find_usages`, and `describe_image` tools for any MCP-compatible client |
| **AST chunking** | 26 languages via tree-sitter (TS, JS, Python, Java, Go, Rust, C/C++, C#, Ruby, Kotlin, Swift, Bash, PHP, PowerShell, SQL, JSON, HTML, CSS, XML (including SVG), YAML, TOML, INI, Dockerfile, Markdown, LaTeX, Razor) |
| **Configurable parsers** | Remap file extensions to any parser via `chunking.parsers` (e.g. `.c` → `cpp`, or index a new `.cu` as C++) — applied to chunking, `get_file_skeleton`, and read labels ([docs](doc/chunking.md#parser-overrides-per-extension-chunkingparsers)) |
| **Document support** | Markdown, LaTeX, PDF, DOCX, DOC, Excel |
| **Image indexing** | Describe images via vision LLM and store descriptions as searchable vector chunks |
| **Hybrid search** | Vector similarity + TF×IDF keyword fusion |
| **Decision model** | Local [tev1](https://ollama.com/library/tev1) classification — `make_decision` labels, routes, and scores short text with probabilities (40–150 ms warm); optional pre-ask routing so the agent asks fewer questions |
| **OpenCode plugin** | Auto-inject context, read-tool override, TUI settings, Ctrl+Enter to add RAG context, MCP registration on `init` |
| **Incremental indexing** | File-hash manifest, background watcher, auto-rebuild on corruption |
| **Privacy-first** | All processing stays local (when using Ollama) |
| **CLI Tools** | `init`, `index`, `query`, `status`, `list`, `show`, `dump`, `clear`, `describe-image`, `decide`, `ui`, `mcp`, `setup`, `quirk`, `eval:sessions`, `eval:analyze`, `eval:compare` |
| **Proxy-aware** | Corporate proxy support with raw-socket localhost bypass |
| **OpenAI / Anthropic / Cohere** | Use alternate embedding providers with API key auto-resolution |
| **Evaluation** | Session-level token tracking, RAG-on vs RAG-off comparison, tiktoken BPE counting |
| **Documentation mode** | `/doc` slash command: agent adds JSDoc/TSDoc to undocumented files, progress tracked per subdirectory |
| **Wiki mode** | `/wiki` slash command: agent maintains a persistent knowledge wiki at `.opencode/wiki/` (ingest, query, lint, seed) |
| **Context optimization** | Post-retrieval dedup, per-file chunk limits, adjacent-merge to fit the context window |
| **Quirk memory** | Persistent experiential memory — agents recall/persist gotchas, preferences, decisions across sessions (`add_quirk` / `recall_quirks`, `opencode-rag quirk`) |
| **AGENTS.md directive** | `opencode-rag init` merges a tool-usage directive into `AGENTS.md` via sentinel markers |
## Web UI
A browser-based dashboard for exploring the indexed vector database - browse, visualize and inspect chunks and evaluate the OpenCode sessions in terms of retrieved chunks, consumed tokens and more.
Launch with `opencode-rag ui`. See [Web UI documentation](doc/webui.md) for details.
## Documentation
| Document | Contents |
|---|---|
| [Architecture](doc/architecture.md) | Module design, data flow, tech stack |
| [Installation](doc/installation.md) | Full install guide, global setup, uninstall |
| [Configuration](doc/configuration.md) | All options: embedding, indexing, retrieval, description, image description, decision, plugin |
| [Chunking](doc/chunking.md) | Language matrix, adding new chunkers, custom chunkers |
| [Embedding](doc/embedding.md) | Providers, model recommendations, proxy, dimension probing |
| [Retrieval](doc/retrieval.md) | Pipeline, hybrid search, score fusion, caching |
| [Plugin](doc/plugin.md) | OpenCode integration, tools, hooks, TUI, troubleshooting |
| [CLI Reference](doc/cli.md) | All commands, options, examples |
| [Web UI](doc/webui.md) | Dashboard, chunk browser, file explorer, compare view |
| [Evaluation](doc/evaluation.md) | Token analysis, session logging, benchmark runner, accuracy guide |
| [Development](doc/development.md) | Setup, testing, conventions, adding providers |
| [Troubleshooting](doc/troubleshooting.md) | Common issues, logging, debugging |
| [Roadmap](doc/roadmap.md) | Completed items, short/mid/long-term plans |
## Decision Model (`make_decision`)
OpenCodeRAG answers fast **classification, routing, policy, and scoring questions** with a local decision model — Together AI's [tev1](https://ollama.com/library/tev1) via Ollama's `/v1/systemone` endpoint. Unlike chat models, tev1 scores a short `state` against 1–64 named questions and returns the chosen option with probabilities — typically in **40–150 ms warm**, without spending agent tokens.
| Question type | Use it for | Example |
|---|---|---|
| `choice` | Pick one of 2–24 options | "Which support intent is this?" → duplicate_charge / cancel / none |
| `noul` | True/false probability | "Does the customer explicitly ask for a refund?" |
| `score` | Place the input on a rubric | "How severe is this incident?" → cosmetic … critical |
One call, two questions:
```json
{
"state": "Customer: I was charged twice for the October subscription ($19.99 each). Please refund the extra charge.",
"questions": [
{ "id": "intent", "type": "choice", "instructions": "Which support intent matches?",
"criteria": { "duplicate_charge": "Charged more than once", "cancel": "Wants to cancel", "none": "None of the above" } },
{ "id": "refund", "type": "noul", "instructions": "Does the customer explicitly ask for a refund?" }
]
}
```
```
**Decision** — ollama/tev1:0.8b
- **intent** = `duplicate_charge` (confidence 0.97)
- **refund** = true (p=0.96)
```
**Prerequisites:** Ollama ≥ 0.35 and a pulled model:
```bash
ollama pull tev1:0.8b # 812 MB, fast — good for quick labels and CI
ollama pull tev1:4b # 4.4 GB, more accurate — recommended when scoring
```
**Disabled by default** — opt in via `decision.enabled`:
```json
{
"decision": {
"enabled": true,
"provider": "ollama",
"model": "tev1:0.8b",
"keepAlive": "30m",
"routeBeforeAsking": false
}
}
```
**Using it well:** always include a `none` / "cannot be determined" option; keep `state` to the relevant excerpt (the effective context is ~2k tokens); treat `confidence < ~0.3` as undecided; don't use it for factual recall or as the only check for high-stakes decisions.
**Pre-ask routing (optional):** with `decision.routeBeforeAsking: true`, the injected agent guidance tells the agent to resolve option choices through `make_decision` before asking you — proceeding on a confident answer and asking only when the model is undecided or the choice is preference-based. Off by default.
`opencode-rag decide` exposes the same engine from the CLI, and `init` creates a dedicated `make-decision` agent skill. See [Plugin documentation](doc/plugin.md#make_decision) and [Configuration](doc/configuration.md#decision).
## Image Indexing
OpenCodeRAG can index image files (PNG, JPEG, WebP, etc.) by sending them to a vision-capable LLM and storing the generated text descriptions as searchable vector chunks. This makes visual assets discoverable via natural language queries (e.g., "login screen screenshot", "architecture diagram").
**Supported providers:** Ollama, OpenAI, Anthropic, Google Gemini, and OpenCode Zen (`opencode`/`opencode-go`) compatible providers.
**Disabled by default** — enable in `opencode-rag.json` to opt in (recommended for dedicated GPUs).
## Documentation Mode
When `documentationMode.enabled` is `true`, the OpenCode plugin exposes a `/doc` slash command that drives the agent to add JSDoc/TSDoc comments to undocumented source files. No agent tools are registered — documentation is driven entirely through the slash command and the documentation system prompt.
```json
{
"documentationMode": {
"enabled": true,
"batchSize": 5
}
}
```
**Workflow:** Type `/doc` to list all undocumented files grouped by subdirectory. The agent picks a subdirectory, documents every public symbol (preserving existing comments and implementation code), then types `/doc src/auth/` to mark that subdirectory complete. Progress is persisted in `.opencode/rag_db/doc-mode-progress.json` so subsequent sessions resume where you left off.
See [Plugin documentation](doc/plugin.md#5-documentation-mode--slash-command-doc) for details.
## Wiki Mode
When `wikiMode.enabled` is `true`, the OpenCode plugin injects a wiki-maintainer system prompt that instructs the agent to build and maintain a persistent knowledge wiki at `.opencode/wiki/` — a structured, interlinked collection of markdown pages synthesizing knowledge from the codebase, docs, and conversations.
```json
{
"wikiMode": {
"enabled": true
}
}
```
**Slash commands:**
| Command | Action |
|---|---|
| `/wiki` | Show wiki status (page count, subdirectories, index/log presence, latest log entry) |
| `/wiki seed` | Generate the initial wiki from README, file structure, and code patterns |
| `/wiki lint` | Health-check for orphan pages, stale source refs, contradictions, missing cross-links |
The agent maintains all wiki pages during normal coding sessions (ingest on learning). The user never writes wiki pages directly. The wiki is git-trackable in `.opencode/` so every edit is a diff.
See [Plugin documentation](doc/plugin.md#6-wiki-mode--slash-command-wiki) for the full protocol.
## Quirk Memory
OpenCodeRAG gives your agent **persistent, cross-session memory** of non-obvious facts — gotchas, preferences, decisions, and environment constraints — that it can recall and extend over time. Quirks are embedded and stored in the same vector store as your code, then **automatically injected into the agent's context on every user message** when their relevance score exceeds the configured threshold. Injection uses two thresholds: the stricter `recallMinScore` (0.72) for the user message context, and the more permissive `autoInjectMinScore` (0.45) for the system prompt. This lets the agent avoid repeating mistakes and accumulate project knowledge across sessions without manual recall.
**Enabled by default.** Turn it on/off in `opencode-rag.json`:
```json
{
"memory": {
"enabled": true,
"autoInject": true,
"minConfidence": 0.5,
"recallMinScore": 0.8,
"autoInjectMinScore": 0.6,
"autoInjectTopK": 2,
"autoInjectLatencyBudgetMs": 2000,
"decay": { "enabled": false, "halfLifeDays": 30 }
}
}
```
**Agent tools:**
| Tool | Use when |
|------|----------|
| `recall_quirks(query)` | You hit an error or need to remember a gotcha, preference, or decision from past sessions |
| `add_quirk(content, { type, tags })` | You just discovered a non-obvious fact, workaround, or convention worth remembering |
| `update_quirk(id, { content, type, tags })` | A recalled quirk is outdated or wrong — fix it instead of adding a duplicate |
| `delete_quirk(id)` | A quirk is fixed, obsolete, or no longer applies — remove it |
**CLI — manage quirks directly:**
```bash
opencode-rag quirk add "npm needs --legacy-peer-deps" --type gotcha --tag installation
opencode-rag quirk list
opencode-rag quirk update <id> --content "..." --type decision
opencode-rag quirk rm <id>
opencode-rag quirk lint # flag low-confidence / stale / duplicate quirks
opencode-rag quirk test "npm needs --legacy-peer-deps"
# ✓ Quirk has been appended:
# [gotcha] npm needs --legacy-peer-deps (installation)
# 99% confidence
```
When `memory.autoInject` is `true`, the plugin checks for relevant quirks on every user message using the combined agent-response + user-query as the search query. Quirks are only injected when their relevance score exceeds the threshold — `recallMinScore` (default 0.72) for the user message, `autoInjectMinScore` (default 0.45) for the system prompt. A latency budget (`autoInjectLatencyBudgetMs`, default 2000ms) prevents slow embedders from blocking message processing. To avoid polluting the context window, each quirk is injected **at most once per session** — once recalled, it is filtered out from all subsequent auto-injections. Every `add_quirk` and every content-changing `update_quirk` is vetted by an immutable trust monitor that rejects destructive patterns (e.g. `rm -rf`, `force push`, `bypass security`). Outdated or fixed quirks should be corrected with `update_quirk` / `delete_quirk` rather than left to contradict newer memory. See [Plugin documentation](doc/plugin.md#9-quirk-memory-experiential-memory) and [CLI Reference: `quirk`](doc/cli.md#quirk).
## MCP Server (Optional)
OpenCodeRAG ships a CLI-based [MCP (Model Context Protocol)](https://spec.modelcontextprotocol.io/) server that exposes semantic code tools to any MCP-compatible client (Claude Desktop, Cursor, etc.).
```bash
opencode-rag mcp
```
> **Note:** The MCP server is **optional**. When running as an OpenCode plugin, the tools are registered **in-process** and work without the MCP server. The `chat.message` hook for hotkey injection also runs in-process. The MCP server is only needed when an **external** MCP client connects to OpenCodeRAG. The plugin auto-starts the server only if `mcp.enabled` is `true` in your config (default: `false`).
### MCP Tools
| Tool | Description |
|------|-------------|
| `search_semantic` | Vector + keyword hybrid search across the indexed codebase |
| `get_file_skeleton` | AST-based file outline (functions, classes, methods) |
| `find_usages` | Find all references to a symbol by name |
| `describe_image` | Describe an image file with the configured vision model (`imageDescription.onDemand` overrides apply) |
| `make_decision` | Classify/route/score short text with the local tev1 decision model (only when `decision.enabled` is `true`) |
Clients can configure the MCP server manually, or `opencode-rag init` auto-registers it.
## Agent Discovery
OpenCodeRAG registers tools that agents can invoke directly. Agents discover these tools via the OpenCode **skill system** - `opencode-rag init` creates `.opencode/skills/opencode-rag/SKILL.md` (workflow guidance) and `.opencode/skills/make-decision/SKILL.md` (decision-model guidance):
1. **Skeleton first** - `get_file_skeleton(filePath)` to orient in a file
2. **Find usages** - `find_usages(symbolName)` before editing any symbol
3. **Search** - `search_semantic(query)` to find relevant code
4. **Describe images** - `describe_image(filePath)` when context involves an image
5. **Decide** - `make_decision(state, questions)` when a task reduces to a choice, true/false check, or rubric score over short text (when `decision.enabled`; with `decision.routeBeforeAsking` the agent resolves such choices before asking you)
6. **Read** - use `read` on specific line ranges
7. **Edit** - make changes with full context
### Available Tools
| Tool | Purpose | When to Use |
|------|---------|-------------|
| `search_semantic` | General-purpose code retrieval | Before any code task when you haven't read the relevant code |
| `get_file_skeleton` | Quick file overview via AST | Before reading a large file to decide which sections matter |
| `find_usages` | Symbol reference search | **Before editing** any function, variable, or class |
| `describe_image` | Live image description via the configured vision model | When a user asks about a screenshot, diagram, or visual asset |
| `make_decision` | Live classification/routing/scoring via the local tev1 decision model (when enabled) | When a task reduces to a choice, true/false check, or rubric score over short text |
| `read` (optional) | RAG-enhanced file read | Full file contents with supplementary context chunks |
## OpenCode Integration
When using OpenCode, the plugin enhances your agent with three discovery mechanisms:
### 1. Skill-Based Discovery
`opencode-rag init` creates `.opencode/skills/opencode-rag/SKILL.md` (tool workflow) and `.opencode/skills/make-decision/SKILL.md` (decision-model usage). Agents load them on demand via the `skill` tool, keeping token overhead minimal.
### 2. System Prompt Guidance
When chunks are indexed, a brief tool list is prepended to the system prompt so agents know the tools exist. This is skipped when no chunks are indexed to save tokens.
### 3. On-Demand RAG Context (Ctrl+Enter / Ctrl+Alt+Enter)
Press **Ctrl+Enter** in the terminal prompt to retrieve and append a relevant file list to your current prompt. Press **Ctrl+Alt+Enter** to append full code chunks instead. The query is taken from your typed text - if the prompt is empty, a toast reminds you to type first. Results are appended directly to the prompt as formatted code blocks with file paths, line ranges, and relevance scores. No dialogs are opened. Keybindings are configurable in the settings menu (Ctrl+Shift+R).
---
## Evaluation & Token Analysis
OpenCodeRAG tracks token usage, RAG injection overhead, and costs across sessions. Compare RAG-on vs RAG-off to measure whether semantic retrieval saves tokens.
```bash
opencode-rag eval:sessions # list sessions
opencode-rag eval:analyze <id> # detailed breakdown
opencode-rag eval:compare <A> <B> # side-by-side comparison
```
Token counting uses tiktoken BPE (cl100k_base) for accurate code tokenization. See [Evaluation documentation](doc/evaluation.md) for details.
---
## Privacy & Security
**100% local by default.** By default, embeddings are generated locally via Ollama. The vector database stays in your project directory. **No source code or embeddings leave your machine** unless you explicitly configure to use a third-party API.
## License
MIT
Connection Info
You Might Also Like
No recommendations available