OpenCodeRAG is a local-first RAG plugin for semantic code and image search. 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 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.
⚠️ Note: Don't confuse this with the npm packageopencode-rag(a discontinued project by a different author).
# 1. Install globally (automatically sets up the OpenCode runtime)
npm install -g opencode-rag-plugin
# 2. Initialize in your project
cd /path/to/your/project
opencode-rag init
# 3. Index your workspace
opencode-rag index
# 4. CLI search test
opencode-rag query "authentication middleware"Prerequisites: Node.js v22+, Ollama (default) or other LLM-hosters (OpenAI-, Google- or Anthropic-compatible).
Contributors / developers: Clone the repo and use
npm install --legacy-peer-deps; npm run build— see Development docs.
| 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) |
| 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 |
| 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, 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 |
A browser-based dashboard for exploring the indexed vector database - browse 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 for details.
| Document | Contents |
|---|---|
| Architecture | Module design, data flow, tech stack |
| Installation | Full install guide, global setup, uninstall |
| Configuration | All options: embedding, indexing, retrieval, description, image description, plugin |
| Chunking | Language matrix, adding new chunkers, custom chunkers |
| Embedding | Providers, model recommendations, proxy, dimension probing |
| Retrieval | Pipeline, hybrid search, score fusion, caching |
| Plugin | OpenCode integration, tools, hooks, TUI, troubleshooting |
| CLI Reference | All commands, options, examples |
| Web UI | Dashboard, chunk browser, file explorer, compare view |
| Evaluation | Token analysis, session logging, benchmark runner, accuracy guide |
| Development | Setup, testing, conventions, adding providers |
| Troubleshooting | Common issues, logging, debugging |
| Roadmap | Completed items, short/mid/long-term plans |
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 compatible providers.
Disabled by default — enable in opencode-rag.json to opt in (recommended for dedicated GPUs).
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.
{
"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 for details.
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.
{
"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 for the full protocol.
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:
{
"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 |
CLI — manage quirks directly:
opencode-rag quirk add "npm needs --legacy-peer-deps" --type gotcha --tag installation
opencode-rag quirk list
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% confidenceWhen 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 is vetted by an immutable trust monitor that rejects destructive patterns (e.g. rm -rf, force push, bypass security). See Plugin documentation and CLI Reference: quirk.
OpenCodeRAG ships a CLI-based MCP (Model Context Protocol) server that exposes semantic code tools to any MCP-compatible client (Claude Desktop, Cursor, etc.).
opencode-rag mcpNote: The MCP server is optional. When running as an OpenCode plugin, the four tools are registered in-process and work without the MCP server. The
chat.messagehook 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 ifmcp.enabledistruein your config (default:false).
| 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 |
Return the pre-generated description for an indexed image file |
Clients can configure the MCP server manually, or opencode-rag init auto-registers it.
OpenCodeRAG registers tools that agents can invoke directly. Agents discover these tools via the OpenCode skill system - when opencode-rag init runs, it creates .opencode/skills/opencode-rag/SKILL.md which teaches agents the recommended workflow:
- Skeleton first -
get_file_skeleton(filePath)to orient in a file - Find usages -
find_usages(symbolName)before editing any symbol - Search -
search_semantic(query)to find relevant code - Describe images -
describe_image(filePath)when context involves an image - Read - use
readon specific line ranges - Edit - make changes with full context
| 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 |
Retrieve pre-generated image description | When a user asks about a screenshot, diagram, or visual asset |
read (optional) |
RAG-enhanced file read | Full file contents with supplementary context chunks |
When using OpenCode, the plugin enhances your agent with three discovery mechanisms:
opencode-rag init creates .opencode/skills/opencode-rag/SKILL.md - an OpenCode skill that teaches agents the tool workflow. Agents load it on demand via the skill tool, keeping token overhead minimal.
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.
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).
OpenCodeRAG tracks token usage, RAG injection overhead, and costs across sessions. Compare RAG-on vs RAG-off to measure whether semantic retrieval saves tokens.
opencode-rag eval:sessions # list sessions
opencode-rag eval:analyze <id> # detailed breakdown
opencode-rag eval:compare <A> <B> # side-by-side comparisonToken counting uses tiktoken BPE (cl100k_base) for accurate code tokenization. See Evaluation documentation for details.
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.
MIT