OpenCodeRAG plugin
Semantic code search, cross-session memory and shell command checks for OpenCode. Runs locally on Ollama, with MCP and CLI modes
- 64 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The plugin writes an index and notes into the project, runs local models and, when the guard is on, scores shell commands.
Install
- Works in
Manual install
npm install -g opencode-rag-pluginThe first quick start command. Then `opencode-rag setup` and `opencode-rag index` in the project directory.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The plugin writes an index and notes into the project, runs local models and, when the guard is on, scores shell commands.
This is third-party code. Review the repository files before installing.
What it does
`OpenCodeRAG` is an OpenCode plugin that builds a local code index and hands the agent the relevant fragments instead of whole files. Search is hybrid, by meaning and by exact names, and chunks follow the syntax tree. It adds memory for notes and decisions that reach the context of later sessions, a project wiki, image description by a local model and a `/doc` documentation mode. It runs through Ollama by default, so code stays on the machine. Opt-in modules are a decision model for classification and a shell guard that scores commands before they run. The same set is available as an MCP server and as the `opencode-rag` CLI.
Who it is for. OpenCode users and users of other agents who work in large repositories and want to save tokens and keep notes across sessions.
Good fit when
- The repository is large and the agent reads whole files for one function
- Project decisions and gotchas must survive between sessions
- Shell commands should get a second opinion from a local model before they run
- Undocumented code needs descriptions through `/doc`
Not a fit when
- Node.js 22 or Ollama is missing and you do not want to install them
- You need sandbox-grade protection, since the shell guard is only a safety net
- The project is small and an index will not repay the setup
Example request
Find the code that checks authorization in middleware and show files with line ranges without reading them whole.Limitations
It needs Node.js 22 or newer and Ollama (the default provider). Search quality depends on the embedding model, and light CPU models trade accuracy for speed. Image description wants a GPU and is otherwise disabled. The shell guard costs one model call per command (about 200 ms) and fails open by default: it is a safety net, not a sandbox. The decision model supports only the Ollama `/v1/systemone` endpoint. ClickHouse is opt-in and needs a server.
How to disable. Run `npm uninstall -g opencode-rag-plugin`, remove the plugin entries from `.opencode/` in the project and delete the index. Runtime files live in `~/.opencode/`.
FAQ
How do I install it?
Run `npm install -g opencode-rag-plugin`, then `opencode-rag setup` in the project and `opencode-rag index`. A wizard configures models, and once OpenCode starts the tools are available to the agent.
Does code leave the machine?
Not by default: Ollama computes embeddings locally and the database stays in the project directory. Code leaves only if you configure a third-party API.
Can I use it without OpenCode?
Yes, the CLI and MCP server work without it. MCP is off by default: set `mcp.enabled` or wire it manually.
What is the shell guard?
A local model scores a command for destructive or malicious intent before it runs. It is off by default and enabled with `setup --shell-guard on`.
How do I add a memory note?
With `opencode-rag quirk add "npm needs --legacy-peer-deps" --type gotcha --tag installation`. The note is injected into context when relevant.
Discussion
No questions or reviews yet.
Related
PluginsAn OpenCode plugin that runs a team of parallel agents with separate sessions, a shared task board and messaging
Self-hosted AI coding agent with a web interface: project map, decision memory, local models via Ollama and permission modes
Orchestrator plugin for OpenCode and Codex CLI: multiple agents, hooks, built-in MCPs, ultrawork mode and hash-anchored edits
An open source coding agent for the terminal and desktop with build and plan modes
Coding memory across sessions, machines and teammates: decisions and dead ends flow into later prompts on their own.
A terminal AI coding agent built on opencode: any model with your own keys, subagent swarms, goals and output compression.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| OpenCodeRAG (this card) | no | 64 | ||
| MCP Local RAG | no | not required | 430 | local document search, while this adds a code index, memory, a wiki and command checks |
| code-graph-rag | no | not required | 5,352 | builds a code graph, while OpenCodeRAG searches by meaning and names and keeps notes across sessions |
README in short
The README lists capabilities (search, memory, decisions, protection, documentation, vision, measurement), a quick start, how hybrid search works, a tool reference, configuration, privacy and limitations.