OpenCodeRAG

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 package opencode-rag (a discontinued project by a different author).

Quick Start

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

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

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 for details.

Documentation

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

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

{
  "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.

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.

{
  "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.

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:

{
  "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:

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 and CLI Reference: quirk.

MCP Server (Optional)

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 mcp

Note: 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.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 | Return the pre-generated description for an indexed image file |

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 - when opencode-rag init runs, it creates .opencode/skills/opencode-rag/SKILL.md which teaches agents the recommended workflow:

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. Read - use read on specific line ranges
6. 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 | 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 |

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 - an OpenCode skill that teaches agents the tool workflow. Agents load it 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.

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