opencode-rag-plugin 2.11.2 → 2.12.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/ReadMe.md +305 -207
- package/dist/cli/commands/backend-detect.d.ts +1 -1
- package/dist/cli/commands/backend-detect.js +1 -1
- package/dist/cli/commands/index.d.ts +0 -1
- package/dist/cli/commands/index.js +0 -1
- package/dist/cli/commands/setup.js +271 -85
- package/dist/cli/commands/{init-helpers.d.ts → workspace-helpers.d.ts} +10 -7
- package/dist/cli/commands/{init-helpers.js → workspace-helpers.js} +12 -62
- package/dist/cli/index.js +1 -2
- package/dist/cli/prompt.d.ts +84 -0
- package/dist/cli/prompt.js +247 -0
- package/dist/cli/types.d.ts +16 -17
- package/dist/cli/wizard/apply.d.ts +58 -0
- package/dist/cli/wizard/apply.js +234 -0
- package/dist/cli/wizard/flow.d.ts +83 -0
- package/dist/cli/wizard/flow.js +759 -0
- package/dist/cli/wizard/model-catalog.d.ts +80 -0
- package/dist/cli/wizard/model-catalog.js +414 -0
- package/dist/cli/wizard/types.d.ts +94 -0
- package/dist/cli/wizard/types.js +5 -0
- package/dist/cli/workspace.d.ts +40 -0
- package/dist/cli/workspace.js +322 -0
- package/dist/cli.d.ts +1 -1
- package/dist/cli.js +1 -1
- package/dist/core/config.d.ts +2 -2
- package/dist/core/config.js +2 -2
- package/dist/core/provider-defaults.d.ts +2 -0
- package/dist/core/provider-defaults.js +4 -0
- package/dist/eval/fast-index.js +1 -1
- package/dist/opencode/system-guidance.d.ts +1 -1
- package/dist/opencode/system-guidance.js +1 -1
- package/dist/tui.d.ts +11 -0
- package/dist/tui.js +12 -1
- package/package.json +1 -1
- package/dist/cli/commands/init.d.ts +0 -51
- package/dist/cli/commands/init.js +0 -508
package/ReadMe.md
CHANGED
|
@@ -1,130 +1,252 @@
|
|
|
1
|
-
|
|
1
|
+
# OpenCodeRAG
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Semantic code search for AI coding agents — local-first, token-efficient, and fast.**
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
OpenCodeRAG indexes your repository as AST-aware chunks with embeddings, then answers natural-language queries with the most relevant code, so an agent no longer has to read whole files to find one function. It installs as an [OpenCode](https://opencode.ai) plugin and also runs as an MCP server or a standalone CLI for other AI harnesses. Everything works locally with [Ollama](https://ollama.ai) by default, and small embedding models run fine on a modern CPU — no dedicated GPU required.
|
|
6
6
|
|
|
7
7
|
[](https://www.npmjs.com/package/opencode-rag-plugin)
|
|
8
8
|
|
|
9
|
-
>
|
|
10
|
-
|
|
11
|
-
>
|
|
9
|
+
> **Package name:** install `opencode-rag-plugin`. The npm package `opencode-rag` is an unrelated, discontinued project by a different author.
|
|
10
|
+
|
|
11
|
+
> **Shell Guard (optional):** every `shell`/`bash` command is classified by the local decision model *before it runs*. Flagged commands ask for confirmation with the full verdict (destructive/malicious probabilities plus a risk category); clean commands run unchanged. See [Shell Guard](#shell-guard-optional).
|
|
12
|
+
|
|
13
|
+
## Contents
|
|
14
|
+
|
|
15
|
+
- [Why OpenCodeRAG](#why-opencoderag)
|
|
16
|
+
- [Quick Start](#quick-start)
|
|
17
|
+
- [How It Works](#how-it-works)
|
|
18
|
+
- [Features](#features)
|
|
19
|
+
- [Using OpenCodeRAG](#using-opencoderag)
|
|
20
|
+
- [MCP Tools](#mcp-tools)
|
|
21
|
+
- [Plugin-Only Tools](#plugin-only-tools)
|
|
22
|
+
- [With OpenCode](#with-opencode)
|
|
23
|
+
- [With Other MCP Clients](#with-other-mcp-clients)
|
|
24
|
+
- [From the CLI](#from-the-cli)
|
|
25
|
+
- [Quirk Memory](#quirk-memory)
|
|
26
|
+
- [Decision Model](#decision-model-make_decision)
|
|
27
|
+
- [Shell Guard (Optional)](#shell-guard-optional)
|
|
28
|
+
- [Documentation and Wiki Modes](#documentation-and-wiki-modes)
|
|
29
|
+
- [Image Indexing](#image-indexing)
|
|
30
|
+
- [Web UI](#web-ui)
|
|
31
|
+
- [Evaluation and Calibration](#evaluation-and-calibration)
|
|
32
|
+
- [Configuration](#configuration)
|
|
33
|
+
- [Documentation Index](#documentation-index)
|
|
34
|
+
- [Privacy and Security](#privacy-and-security)
|
|
35
|
+
- [Limitations and Non-Goals](#limitations-and-non-goals)
|
|
36
|
+
- [Contributing and Support](#contributing-and-support)
|
|
37
|
+
- [License](#license)
|
|
38
|
+
|
|
39
|
+
## Why OpenCodeRAG
|
|
40
|
+
|
|
41
|
+
- **Fewer tokens.** Retrieval returns the handful of relevant chunks instead of whole files, so the agent spends its context on the code that actually matters.
|
|
42
|
+
- **Search the way code is written.** AST-aware chunking keeps functions and classes intact, and hybrid vector + keyword search catches both meaning ("where is auth handled?") and exact symbol names.
|
|
43
|
+
- **Local by default.** Embeddings, the vector store, and the optional decision model run on your machine. No source code leaves the workspace unless you explicitly configure a hosted provider.
|
|
44
|
+
- **Scales with the repository.** Incremental indexing, a background watcher, and an optional shared ClickHouse store keep large or multi-machine workspaces searchable.
|
|
12
45
|
|
|
13
46
|
## Quick Start
|
|
14
47
|
|
|
48
|
+
**Prerequisites:** Node.js v22+ and [Ollama](https://ollama.ai) (default provider). [OpenCode](https://opencode.ai) is optional — the CLI and MCP server work without it.
|
|
49
|
+
|
|
15
50
|
```bash
|
|
16
|
-
# 1. Install
|
|
51
|
+
# 1. Install the plugin and the CLI
|
|
17
52
|
npm install -g opencode-rag-plugin
|
|
18
53
|
|
|
19
|
-
# 2.
|
|
54
|
+
# 2. Set up the runtime, the workspace, and your models
|
|
55
|
+
# (a short interactive wizard asks which models to use)
|
|
20
56
|
cd /path/to/your/project
|
|
21
57
|
opencode-rag setup
|
|
22
58
|
|
|
23
|
-
# 3.
|
|
59
|
+
# 3. Build the index
|
|
24
60
|
opencode-rag index
|
|
25
61
|
|
|
26
|
-
# 4.
|
|
62
|
+
# 4. Search from the terminal
|
|
27
63
|
opencode-rag query "authentication middleware"
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Example output:
|
|
67
|
+
|
|
68
|
+
```text
|
|
69
|
+
Querying: "authentication middleware"
|
|
70
|
+
Top-K: 10
|
|
71
|
+
Searching 1240 indexed chunks...
|
|
72
|
+
|
|
73
|
+
3 result(s) in 41ms:
|
|
74
|
+
|
|
75
|
+
src/auth/middleware.ts:12-48
|
|
76
|
+
Score: 0.8123
|
|
77
|
+
...
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
That is the whole setup. Open OpenCode in the same directory and the agent can use the retrieval tools right away.
|
|
81
|
+
|
|
82
|
+
`opencode-rag setup` does the whole onboarding in one command: it installs or verifies the machine-level runtime in `~/.opencode/`, scaffolds the current workspace (`.opencode/` config, plugin entries, skill files), and — on the first run, or whenever you pass `--reconfigure` — walks you through a **model wizard** for the embedding, description, vision, and decision models. A plain re-run just syncs the workspace files. The wizard is scriptable (`--yes`, `--provider`, `--base-url`, `--embedding-model`, `--no-description`, …), and `--skip-runtime` limits the run to the workspace. Use `opencode-rag update` to upgrade the runtime to a newer release.
|
|
83
|
+
|
|
84
|
+
**Other package managers:** `pnpm add -g opencode-rag-plugin`, `yarn global add opencode-rag-plugin`, and `bun add -g opencode-rag-plugin` work as drop-in replacements. Setup and update detect the package manager that owns the install, so npm does not need to be on `PATH`.
|
|
85
|
+
|
|
86
|
+
### Optional add-ons
|
|
87
|
+
|
|
88
|
+
These switchers are off by default and can be turned on later:
|
|
28
89
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
#
|
|
90
|
+
| Add-on | Default | Enable with | Requires |
|
|
91
|
+
|---|---|---|---|
|
|
92
|
+
| [Shell Guard](#shell-guard-optional) | off | `shellGuard.enabled` (or `setup --shell-guard on`) | tev1 via Ollama ≥ 0.35 |
|
|
93
|
+
| [Decision model](#decision-model-make_decision) | off | `decision.enabled` (or `setup --decision on`) | tev1 via Ollama ≥ 0.35 |
|
|
94
|
+
| [Documentation mode](#documentation-mode-doc) | off | `documentationMode.enabled` | nothing extra |
|
|
95
|
+
| [Shared ClickHouse store](doc/clickhouse.md) | off | `vectorStore.provider: "clickhouse"` (or `setup --vector-store clickhouse`) | a ClickHouse server |
|
|
96
|
+
|
|
97
|
+
Two more are on by default and worth switching off if they do not fit your setup: [image descriptions](#image-indexing) (`imageDescription.enabled`, needs a vision model) and [wiki mode](#wiki-mode-wiki) (`wikiMode.enabled`, no extra setup).
|
|
98
|
+
|
|
99
|
+
> **Contributors / developers:** clone the repo and run `npm install --legacy-peer-deps; npm run build` — see the [development docs](doc/development.md).
|
|
100
|
+
|
|
101
|
+
## How It Works
|
|
102
|
+
|
|
103
|
+
```text
|
|
104
|
+
Workspace files
|
|
105
|
+
│ tree-sitter chunking (AST-aware)
|
|
106
|
+
▼
|
|
107
|
+
Chunks ─────► embeddings ─────► vector store (LanceDB by default)
|
|
108
|
+
│
|
|
109
|
+
└─────────► keyword index (TF×IDF)
|
|
110
|
+
|
|
111
|
+
Query ─► vector search + keyword search ─► weighted fusion ─► top-K chunks
|
|
33
112
|
```
|
|
34
113
|
|
|
35
|
-
|
|
114
|
+
1. **Index** — files are split into semantic chunks, optionally described by a local LLM, embedded, and stored alongside a TF×IDF keyword index. A file-hash manifest means only changed files are reprocessed, and a background watcher keeps the index current while you work.
|
|
115
|
+
2. **Retrieve** — the query is embedded and matched against both signals. The scores are fused and post-processed (dedup, per-file chunk limits, adjacent-chunk merging) to fit the context window.
|
|
116
|
+
3. **Use** — the agent calls `search_semantic`, `get_file_skeleton`, or `find_usages` instead of reading entire files.
|
|
117
|
+
|
|
118
|
+
## Features
|
|
119
|
+
|
|
120
|
+
**Retrieval**
|
|
36
121
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
workspace, and `opencode-rag update` upgrades to a newer release.
|
|
122
|
+
- AST chunking for 26 languages via tree-sitter, plus documents (Markdown, LaTeX, PDF, DOCX, Excel) and images.
|
|
123
|
+
- Hybrid search combining vector similarity with TF×IDF keyword matching; the keyword index is repaired from the store whenever it drifts behind it, so the BM25 half never covers only part of the corpus.
|
|
124
|
+
- Retrieval calibration with `opencode-rag eval:tune` against a labelled golden set.
|
|
125
|
+
- Context optimization: dedup, per-file chunk limits, adjacent-chunk merging.
|
|
126
|
+
- Configurable parsers — remap file extensions to any parser via `chunking.parsers` (e.g. `.c` → `cpp`); the override applies to chunking, `get_file_skeleton`, and read labels ([docs](doc/chunking.md#parser-overrides-per-extension-chunkingparsers)).
|
|
43
127
|
|
|
44
|
-
**
|
|
128
|
+
**Agent integration**
|
|
45
129
|
|
|
46
|
-
|
|
130
|
+
- OpenCode plugin with three discovery paths: skill files, system-prompt guidance, and on-demand RAG context on `Ctrl+Enter` / `Ctrl+Alt+Enter`.
|
|
131
|
+
- MCP server for Claude Desktop, Cursor, and any other MCP-compatible client.
|
|
132
|
+
- Read-tool override that adds supplementary RAG chunks to normal file reads.
|
|
133
|
+
- TUI settings panel for models, retrieval options, and keybindings.
|
|
134
|
+
- `AGENTS.md` directive: workspace setup merges a tool-usage directive into `AGENTS.md` via sentinel markers.
|
|
47
135
|
|
|
48
|
-
|
|
136
|
+
**Memory and decisions**
|
|
137
|
+
|
|
138
|
+
- [Quirk memory](#quirk-memory): persistent, cross-session gotchas and decisions with automatic injection into the agent's context.
|
|
139
|
+
- [Decision model](#decision-model-make_decision): local classification, routing, and scoring of short text — no agent tokens spent.
|
|
140
|
+
- Failed tool calls are recorded as quirks, so a later session starts with the fix already known.
|
|
141
|
+
|
|
142
|
+
**Operations**
|
|
143
|
+
|
|
144
|
+
- Incremental indexing with a file-hash manifest, background watcher, and automatic rebuild on corruption.
|
|
145
|
+
- Optional ClickHouse backend for one shared index across many machines and workspaces, with HNSW ANN, epoch rebuilds, and state sync ([docs](doc/clickhouse.md)).
|
|
146
|
+
- Session-level token and cost analysis: RAG-on vs RAG-off comparison with tiktoken BPE counting.
|
|
147
|
+
- Alternate providers: embedding via Ollama, OpenAI-compatible endpoints, or Cohere; description and vision via Anthropic, Google Gemini, or OpenAI-compatible endpoints, with API-key auto-resolution.
|
|
148
|
+
- Proxy-aware HTTP with a raw-socket localhost bypass.
|
|
149
|
+
|
|
150
|
+
## Using OpenCodeRAG
|
|
151
|
+
|
|
152
|
+
### MCP Tools
|
|
49
153
|
|
|
50
|
-
|
|
154
|
+
These five tools are the whole retrieval surface. Inside OpenCode the plugin registers them in-process; over MCP they are served by `opencode-rag mcp`.
|
|
51
155
|
|
|
52
|
-
|
|
|
156
|
+
| Tool | What it does | When the agent uses it |
|
|
157
|
+
|---|---|---|
|
|
158
|
+
| `search_semantic` | Hybrid vector + keyword search over the indexed code | Before a code task, instead of reading whole files |
|
|
159
|
+
| `get_file_skeleton` | AST outline of a file (functions, classes, methods) | To orient in a large file before reading it |
|
|
160
|
+
| `find_usages` | Every reference to a symbol | Before editing a function, class, or variable |
|
|
161
|
+
| `describe_image` | Describes an image with the configured vision model | When the task involves a screenshot, diagram, or other asset |
|
|
162
|
+
| `make_decision` | Classifies, routes, or scores short text (needs `decision.enabled`) | When the answer reduces to a choice, a yes/no check, or a rubric score |
|
|
163
|
+
|
|
164
|
+
### Plugin-Only Tools
|
|
165
|
+
|
|
166
|
+
The quirk tools are registered by the OpenCode plugin (not served over MCP):
|
|
167
|
+
|
|
168
|
+
| Tool | What it does |
|
|
53
169
|
|---|---|
|
|
54
|
-
|
|
|
55
|
-
|
|
|
56
|
-
|
|
|
57
|
-
|
|
|
58
|
-
| **Document support** | Markdown, LaTeX, PDF, DOCX, DOC, Excel |
|
|
59
|
-
| **Image indexing** | Describe images via vision LLM and store descriptions as searchable vector chunks |
|
|
60
|
-
| **Hybrid search** | Vector similarity + TF×IDF keyword fusion — the keyword index is repaired from the store whenever it drifts behind it, so the BM25 half never covers only part of the corpus |
|
|
61
|
-
| **Retrieval calibration** | `opencode-rag eval:tune` sweeps the fusion weights against the labelled golden set and reports (or writes) the best configuration for your embedder and corpus |
|
|
62
|
-
| **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 |
|
|
63
|
-
| **OpenCode plugin** | Auto-inject context, read-tool override, TUI settings, Ctrl+Enter to add RAG context, MCP registration on `init` |
|
|
64
|
-
| **Incremental indexing** | File-hash manifest, background watcher, auto-rebuild on corruption |
|
|
65
|
-
| **Central vector store** | Optional ClickHouse backend (`vectorStore.provider: "clickhouse"`) — one shared index for many machines/workspaces with HNSW ANN, epoch rebuilds and state sync; `opencode-rag clickhouse setup` configures it ([docs](doc/clickhouse.md)) |
|
|
66
|
-
| **Privacy-first** | All processing stays local (when using Ollama) |
|
|
67
|
-
| **CLI Tools** | `init`, `index`, `query`, `status`, `list`, `show`, `dump`, `clear`, `describe-image`, `decide`, `ui`, `mcp`, `setup`, `clickhouse`, `quirk`, `eval:sessions`, `eval:analyze`, `eval:compare`, `eval:gate`, `eval:decide`, `eval:tune` |
|
|
68
|
-
| **Proxy-aware** | Corporate proxy support with raw-socket localhost bypass |
|
|
69
|
-
| **OpenAI / Anthropic / Cohere** | Use alternate embedding providers with API key auto-resolution |
|
|
70
|
-
| **Evaluation** | Session-level token tracking, RAG-on vs RAG-off comparison, tiktoken BPE counting |
|
|
71
|
-
| **Documentation mode** | `/doc` slash command: agent adds JSDoc/TSDoc to undocumented files, progress tracked per subdirectory |
|
|
72
|
-
| **Wiki mode** | `/wiki` slash command: agent maintains a persistent knowledge wiki at `.opencode/wiki/` (ingest, query, lint, seed) |
|
|
73
|
-
| **Context optimization** | Post-retrieval dedup, per-file chunk limits, adjacent-merge to fit the context window |
|
|
74
|
-
| **Quirk memory** | Persistent experiential memory — agents recall/persist gotchas, preferences, decisions across sessions (`add_quirk` / `recall_quirks`, `opencode-rag quirk`); failed tool calls are auto-recorded as quirks |
|
|
75
|
-
| **AGENTS.md directive** | `opencode-rag init` merges a tool-usage directive into `AGENTS.md` via sentinel markers |
|
|
170
|
+
| `recall_quirks` | Recalls stored gotchas, preferences, and decisions from past sessions |
|
|
171
|
+
| `add_quirk` | Stores a new non-obvious fact, workaround, or convention |
|
|
172
|
+
| `update_quirk` | Corrects a stored quirk that is outdated or wrong |
|
|
173
|
+
| `delete_quirk` | Removes a quirk that is fixed, obsolete, or no longer applies |
|
|
76
174
|
|
|
77
|
-
|
|
175
|
+
### With OpenCode
|
|
78
176
|
|
|
79
|
-
|
|
177
|
+
**Discovery.** Workspace setup creates `.opencode/skills/opencode-rag/SKILL.md` (tool workflow) and `.opencode/skills/make-decision/SKILL.md` (decision-model guidance). Agents load them on demand, so idle sessions pay almost no token cost. When the index contains chunks, a brief tool list is also prepended to the system prompt so agents know the tools exist — skipped when nothing is indexed, to save tokens.
|
|
178
|
+
|
|
179
|
+
**Hotkeys.** `Ctrl+Enter` appends a relevant file list to the prompt you are typing; `Ctrl+Alt+Enter` appends full code chunks. The query is taken from your typed text — if the prompt is empty, a toast reminds you to type first. Results land directly in the prompt as code blocks with file paths, line ranges, and relevance scores; no dialog is opened. Keybindings are configurable in the settings menu (Alt+S, or type `/rag-settings`).
|
|
180
|
+
|
|
181
|
+
**Read override.** A normal `read` can return the file plus supplementary RAG chunks that are relevant to the surrounding work.
|
|
182
|
+
|
|
183
|
+
### With Other MCP Clients
|
|
184
|
+
|
|
185
|
+
<a id="mcp-server"></a>
|
|
186
|
+
|
|
187
|
+
```bash
|
|
188
|
+
opencode-rag mcp
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
The MCP server is optional and only needed when an *external* client connects. Inside OpenCode the tools are registered in-process and the hotkey hook runs in-process too. The plugin auto-starts the server only when `mcp.enabled` is `true` (default `false`); clients can also configure it manually, and workspace setup can register it for you.
|
|
192
|
+
|
|
193
|
+
### From the CLI
|
|
194
|
+
|
|
195
|
+
```bash
|
|
196
|
+
opencode-rag setup # install the runtime, scaffold the workspace, run the model wizard
|
|
197
|
+
opencode-rag index # build or update the index
|
|
198
|
+
opencode-rag query "..." # search from the terminal
|
|
199
|
+
opencode-rag status # index health and coverage
|
|
200
|
+
opencode-rag ui # open the web dashboard
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
Further commands: `list`, `show <file>`, `dump`, `clear`, `describe-image`, `decide`, `mcp`, `update`, `clickhouse`, `quirk`, and the `eval:*` family. Run `opencode-rag --help` or see the [CLI reference](doc/cli.md) for every command, flag, and example.
|
|
204
|
+
|
|
205
|
+
## Quirk Memory
|
|
206
|
+
|
|
207
|
+
Quirk memory gives your agent a **persistent, cross-session memory** of non-obvious facts — gotchas, preferences, decisions, and environment constraints. Quirks are embedded and stored in the same vector store as your code, then injected into the agent's context whenever their relevance clears a configurable threshold. The agent stops repeating the same mistake and accumulates project knowledge over time.
|
|
208
|
+
|
|
209
|
+
**Enabled by default.** Configure it in `opencode-rag.json`:
|
|
80
210
|
|
|
81
211
|
```json
|
|
82
212
|
{
|
|
83
|
-
"
|
|
213
|
+
"memory": {
|
|
84
214
|
"enabled": true,
|
|
85
|
-
"
|
|
86
|
-
"
|
|
87
|
-
"
|
|
215
|
+
"autoInject": true,
|
|
216
|
+
"minConfidence": 0.5,
|
|
217
|
+
"recallMinScore": 0.72,
|
|
218
|
+
"autoInjectMinScore": 0.75,
|
|
219
|
+
"autoInjectTopK": 1,
|
|
220
|
+
"autoInjectLatencyBudgetMs": 2000,
|
|
221
|
+
"injectOnToolError": true,
|
|
222
|
+
"autoCreateOnToolError": true,
|
|
223
|
+
"toolErrorCreateMaxPerSession": 2,
|
|
224
|
+
"decay": { "enabled": false, "halfLifeDays": 30 }
|
|
88
225
|
}
|
|
89
226
|
}
|
|
90
227
|
```
|
|
91
228
|
|
|
92
|
-
|
|
93
|
-
- **Fast** — a warm verdict costs ~200–230 ms (`rm -rf ./dist` → 0.96 destructive, `delete_files`; `ls -la src` → 0.23, allowed). Repeated identical commands hit the 10-minute cache.
|
|
94
|
-
- **Machine-wide** — put the block in `~/.config/opencode/opencode-rag.json` (the global layer, see [Configuration](doc/configuration.md#config-file-discovery)) and every workspace inherits it; a workspace config can still override or disable it.
|
|
95
|
-
- **Fail-open by default** (`onError: "allow"`): if the classifier is down or times out, the command runs and a warning is logged. Set `onError: "ask"` to require confirmation instead.
|
|
96
|
-
- **Verdict cache** (10 min, 256 entries): repeated identical commands are answered instantly; the key includes the provider/model, so switching models invalidates it, and cached probabilities are re-scored against the current threshold on every call.
|
|
97
|
-
- **Config edits apply without a restart** — the guard re-reads `opencode-rag.json` when it changes.
|
|
98
|
-
- **Backend** defaults to the `decision` section, and any `/v1/systemone` endpoint works — e.g. llama-swap with `"baseUrl": "http://localhost:11437", "model": "Clef-Flash"`.
|
|
99
|
-
|
|
100
|
-
Every verdict is logged under `scope: shell.guard`, so you can tune the threshold against real commands. See [Configuration](doc/configuration.md#shellguard) and [Plugin documentation](doc/plugin.md#shell-guard-command-vetting).
|
|
101
|
-
|
|
102
|
-
## Web UI
|
|
229
|
+
**How injection works.** On every user message the plugin searches for quirks related to the combined agent response and user query, and injects only those whose raw vector similarity clears `autoInjectMinScore` (default 0.75). Manual `recall_quirks` calls use the slightly looser `recallMinScore` (default 0.72) — raise it to 0.85 to keep only strongly related quirks out of unrelated tasks. A latency budget (`autoInjectLatencyBudgetMs`, default 2000 ms) keeps a slow embedder from blocking message processing, and each quirk is injected **at most once per session**. Every `add_quirk` and every content-changing `update_quirk` passes an immutable trust monitor that rejects destructive patterns (`rm -rf`, `force push`, `bypass security`).
|
|
103
230
|
|
|
104
|
-
|
|
231
|
+
**Failed tool calls become memory.** When a tool call fails, the plugin looks for a stored quirk that covers the failure and injects it into the next request (`memory.injectOnToolError`). If no quirk covers it, it writes one (`memory.autoCreateOnToolError`) from a deterministic template built from the tool name and the error text — no LLM involved. The new quirk is tagged `tool-error` and recorded for *future* sessions; it is deliberately excluded from the generic auto-injection, so a raw error dump never leaks into an unrelated turn. Creation is bounded by a per-session budget (2) and a per-error cooldown (10 minutes), and it is suppressed when a quirk for the same tool and cause class already exists.
|
|
105
232
|
|
|
106
|
-
|
|
233
|
+
**Prevention, not just learning.** Known failure patterns are also injected into the **system prompt before the model picks a tool** (`memory.toolErrorProactiveInject`), scoped to the tools the session can actually call and to durable failure causes only — a rate limit is never warned about in advance, because the next call will not fail the same way. The first occurrence of a failure is unavoidable; every later session is warned up front.
|
|
107
234
|
|
|
108
|
-
|
|
235
|
+
**CLI — manage quirks directly:**
|
|
109
236
|
|
|
110
|
-
|
|
237
|
+
```bash
|
|
238
|
+
opencode-rag quirk add "npm needs --legacy-peer-deps" --type gotcha --tag installation
|
|
239
|
+
opencode-rag quirk list
|
|
240
|
+
opencode-rag quirk update <id> --content "..." --type decision
|
|
241
|
+
opencode-rag quirk rm <id>
|
|
242
|
+
opencode-rag quirk lint # flag low-confidence / stale / duplicate quirks
|
|
243
|
+
opencode-rag quirk test "npm needs --legacy-peer-deps"
|
|
244
|
+
# ✓ Quirk has been appended:
|
|
245
|
+
# [gotcha] npm needs --legacy-peer-deps (installation)
|
|
246
|
+
# 99% confidence
|
|
247
|
+
```
|
|
111
248
|
|
|
112
|
-
|
|
113
|
-
|---|---|
|
|
114
|
-
| [Architecture](doc/architecture.md) | Module design, data flow, tech stack |
|
|
115
|
-
| [Installation](doc/installation.md) | Full install guide, global setup, uninstall |
|
|
116
|
-
| [Configuration](doc/configuration.md) | All options: embedding, indexing, retrieval, description, image description, decision, shell guard, plugin |
|
|
117
|
-
| [Chunking](doc/chunking.md) | Language matrix, adding new chunkers, custom chunkers |
|
|
118
|
-
| [Embedding](doc/embedding.md) | Providers, model recommendations, proxy, dimension probing |
|
|
119
|
-
| [ClickHouse store](doc/clickhouse.md) | Central vector store backend: setup, epochs, ANN, multi-machine sync |
|
|
120
|
-
| [Retrieval](doc/retrieval.md) | Pipeline, hybrid search, score fusion, caching |
|
|
121
|
-
| [Plugin](doc/plugin.md) | OpenCode integration, tools, hooks, TUI, troubleshooting |
|
|
122
|
-
| [CLI Reference](doc/cli.md) | All commands, options, examples |
|
|
123
|
-
| [Web UI](doc/webui.md) | Dashboard, chunk browser, file explorer, compare view |
|
|
124
|
-
| [Evaluation](doc/evaluation.md) | Token analysis, session logging, benchmark runner, accuracy guide |
|
|
125
|
-
| [Development](doc/development.md) | Setup, testing, conventions, adding providers |
|
|
126
|
-
| [Troubleshooting](doc/troubleshooting.md) | Common issues, logging, debugging |
|
|
127
|
-
| [Roadmap](doc/roadmap.md) | Completed items, short/mid/long-term plans |
|
|
249
|
+
See [Plugin documentation](doc/plugin.md#9-quirk-memory-experiential-memory) and [CLI reference: `quirk`](doc/cli.md#quirk).
|
|
128
250
|
|
|
129
251
|
## Decision Model (`make_decision`)
|
|
130
252
|
|
|
@@ -149,7 +271,7 @@ One call, two questions:
|
|
|
149
271
|
}
|
|
150
272
|
```
|
|
151
273
|
|
|
152
|
-
```
|
|
274
|
+
```text
|
|
153
275
|
**Decision** — ollama/tev1:0.8b
|
|
154
276
|
|
|
155
277
|
- **intent** = `duplicate_charge` (confidence 0.97)
|
|
@@ -177,23 +299,42 @@ ollama pull tev1:4b # 4.4 GB, more accurate — recommended when scoring
|
|
|
177
299
|
}
|
|
178
300
|
```
|
|
179
301
|
|
|
180
|
-
**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;
|
|
302
|
+
**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; do not use it for factual recall or as the only check for high-stakes decisions.
|
|
181
303
|
|
|
182
304
|
**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.
|
|
183
305
|
|
|
184
|
-
`opencode-rag decide` exposes the same engine from the CLI, and
|
|
306
|
+
`opencode-rag decide` exposes the same engine from the CLI, and workspace setup creates a dedicated `make-decision` agent skill. See [Plugin documentation](doc/plugin.md#make_decision) and [Configuration](doc/configuration.md#decision).
|
|
185
307
|
|
|
186
|
-
##
|
|
308
|
+
## Shell Guard (Optional)
|
|
187
309
|
|
|
188
|
-
|
|
310
|
+
The same local decision model can vet **every shell command before it runs**. With `shellGuard.enabled: true`, each `shell`/`bash` call is classified for destructive and malicious intent; a command whose `p(destructive)` or `p(malicious)` reaches the threshold is escalated to OpenCode's confirmation prompt with the full verdict — otherwise it executes unchanged.
|
|
189
311
|
|
|
190
|
-
|
|
312
|
+
```json
|
|
313
|
+
{
|
|
314
|
+
"shellGuard": {
|
|
315
|
+
"enabled": true,
|
|
316
|
+
"threshold": 0.5,
|
|
317
|
+
"timeoutMs": 10000,
|
|
318
|
+
"onError": "allow"
|
|
319
|
+
}
|
|
320
|
+
}
|
|
321
|
+
```
|
|
191
322
|
|
|
192
|
-
**
|
|
323
|
+
- **Off by default** — enabling adds one local model call to the critical path of every shell command.
|
|
324
|
+
- **Fast** — a warm verdict costs ~200–230 ms (`rm -rf ./dist` → 0.96 destructive, `delete_files`; `ls -la src` → 0.23, allowed). Repeated identical commands hit the 10-minute cache.
|
|
325
|
+
- **Machine-wide** — put the block in `~/.config/opencode/opencode-rag.json` (the global layer, see [Configuration](doc/configuration.md#config-file-discovery)) and every workspace inherits it; a workspace config can still override or disable it.
|
|
326
|
+
- **Fail-open by default** (`onError: "allow"`) — if the classifier is down or times out, the command runs and a warning is logged. Set `onError: "ask"` to require confirmation instead.
|
|
327
|
+
- **Verdict cache** (10 min, 256 entries) — repeated identical commands are answered instantly; the key includes the provider/model, so switching models invalidates it, and cached probabilities are re-scored against the current threshold on every call.
|
|
328
|
+
- **Config edits apply without a restart** — the guard re-reads `opencode-rag.json` when it changes.
|
|
329
|
+
- **Backend** defaults to the `decision` section, and any `/v1/systemone` endpoint works — e.g. llama-swap with `"baseUrl": "http://localhost:11437", "model": "Clef-Flash"`.
|
|
330
|
+
|
|
331
|
+
Every verdict is logged under `scope: shell.guard`, so you can tune the threshold against real commands. See [Configuration](doc/configuration.md#shellguard) and [Plugin documentation](doc/plugin.md#shell-guard-command-vetting).
|
|
332
|
+
|
|
333
|
+
## Documentation and Wiki Modes
|
|
193
334
|
|
|
194
|
-
|
|
335
|
+
### Documentation Mode (`/doc`)
|
|
195
336
|
|
|
196
|
-
When `documentationMode.enabled` is `true`, the
|
|
337
|
+
When `documentationMode.enabled` is `true`, the 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.
|
|
197
338
|
|
|
198
339
|
```json
|
|
199
340
|
{
|
|
@@ -204,13 +345,13 @@ When `documentationMode.enabled` is `true`, the OpenCode plugin exposes a `/doc`
|
|
|
204
345
|
}
|
|
205
346
|
```
|
|
206
347
|
|
|
207
|
-
**Workflow:**
|
|
348
|
+
**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 later sessions resume where you left off.
|
|
208
349
|
|
|
209
350
|
See [Plugin documentation](doc/plugin.md#5-documentation-mode--slash-command-doc) for details.
|
|
210
351
|
|
|
211
|
-
|
|
352
|
+
### Wiki Mode (`/wiki`)
|
|
212
353
|
|
|
213
|
-
When `wikiMode.enabled` is `true
|
|
354
|
+
When `wikiMode.enabled` is `true` (on by default), the 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.
|
|
214
355
|
|
|
215
356
|
```json
|
|
216
357
|
{
|
|
@@ -220,150 +361,107 @@ When `wikiMode.enabled` is `true`, the OpenCode plugin injects a wiki-maintainer
|
|
|
220
361
|
}
|
|
221
362
|
```
|
|
222
363
|
|
|
223
|
-
**Slash commands:**
|
|
224
|
-
|
|
225
364
|
| Command | Action |
|
|
226
365
|
|---|---|
|
|
227
366
|
| `/wiki` | Show wiki status (page count, subdirectories, index/log presence, latest log entry) |
|
|
228
|
-
| `/wiki seed` | Generate the initial wiki from README, file structure, and code patterns |
|
|
367
|
+
| `/wiki seed` | Generate the initial wiki from the README, file structure, and code patterns |
|
|
229
368
|
| `/wiki lint` | Health-check for orphan pages, stale source refs, contradictions, missing cross-links |
|
|
230
369
|
|
|
231
|
-
The agent maintains all wiki pages during normal coding sessions
|
|
370
|
+
The agent maintains all wiki pages during normal coding sessions; you never write wiki pages yourself. 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.
|
|
232
371
|
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
## Quirk Memory
|
|
236
|
-
|
|
237
|
-
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. Recall is gated by raw vector similarity (0-1, cosine mapped to [0,1]): `recallMinScore` (default 0.72) for manual `recall_quirks` calls, and the stricter `autoInjectMinScore` (default 0.75) for automatic injection - set it high (e.g. 0.85) to keep only strongly related quirks out of unrelated tasks. This lets the agent avoid repeating mistakes and accumulate project knowledge across sessions without manual recall.
|
|
238
|
-
|
|
239
|
-
**Enabled by default.** Turn it on/off in `opencode-rag.json`:
|
|
240
|
-
|
|
241
|
-
```json
|
|
242
|
-
{
|
|
243
|
-
"memory": {
|
|
244
|
-
"enabled": true,
|
|
245
|
-
"autoInject": true,
|
|
246
|
-
"minConfidence": 0.5,
|
|
247
|
-
"recallMinScore": 0.72,
|
|
248
|
-
"autoInjectMinScore": 0.75,
|
|
249
|
-
"autoInjectTopK": 1,
|
|
250
|
-
"autoInjectLatencyBudgetMs": 2000,
|
|
251
|
-
"injectOnToolError": true,
|
|
252
|
-
"autoCreateOnToolError": true,
|
|
253
|
-
"toolErrorCreateMaxPerSession": 2,
|
|
254
|
-
"decay": { "enabled": false, "halfLifeDays": 30 }
|
|
255
|
-
}
|
|
256
|
-
}
|
|
257
|
-
```
|
|
372
|
+
## Image Indexing
|
|
258
373
|
|
|
259
|
-
|
|
374
|
+
OpenCodeRAG can index image files (PNG, JPEG, WebP, and others) by sending them to a vision-capable LLM and storing the generated text descriptions as searchable vector chunks. This makes visual assets discoverable through natural-language queries (e.g. "login screen screenshot", "architecture diagram").
|
|
260
375
|
|
|
261
|
-
|
|
262
|
-
|------|----------|
|
|
263
|
-
| `recall_quirks(query)` | You hit an error or need to remember a gotcha, preference, or decision from past sessions |
|
|
264
|
-
| `add_quirk(content, { type, tags })` | You just discovered a non-obvious fact, workaround, or convention worth remembering |
|
|
265
|
-
| `update_quirk(id, { content, type, tags })` | A recalled quirk is outdated or wrong — fix it instead of adding a duplicate |
|
|
266
|
-
| `delete_quirk(id)` | A quirk is fixed, obsolete, or no longer applies — remove it |
|
|
376
|
+
**Supported providers:** Ollama, OpenAI, Anthropic, Google Gemini, and OpenCode Zen (`opencode`/`opencode-go`) compatible providers.
|
|
267
377
|
|
|
268
|
-
**
|
|
378
|
+
**Enabled by default** — set `imageDescription.enabled: false` in `opencode-rag.json` to skip image files entirely (recommended if you have no vision model or no GPU).
|
|
269
379
|
|
|
270
|
-
|
|
271
|
-
opencode-rag quirk add "npm needs --legacy-peer-deps" --type gotcha --tag installation
|
|
272
|
-
opencode-rag quirk list
|
|
273
|
-
opencode-rag quirk update <id> --content "..." --type decision
|
|
274
|
-
opencode-rag quirk rm <id>
|
|
275
|
-
opencode-rag quirk lint # flag low-confidence / stale / duplicate quirks
|
|
276
|
-
opencode-rag quirk test "npm needs --legacy-peer-deps"
|
|
277
|
-
# ✓ Quirk has been appended:
|
|
278
|
-
# [gotcha] npm needs --legacy-peer-deps (installation)
|
|
279
|
-
# 99% confidence
|
|
280
|
-
```
|
|
380
|
+
## Web UI
|
|
281
381
|
|
|
282
|
-
|
|
382
|
+
A browser-based dashboard for exploring the indexed vector database — browse, visualize, and inspect chunks, and evaluate OpenCode sessions in terms of retrieved chunks and consumed tokens.
|
|
283
383
|
|
|
284
|
-
|
|
384
|
+

|
|
285
385
|
|
|
286
|
-
|
|
386
|
+
Launch with `opencode-rag ui`. See the [Web UI documentation](doc/webui.md) for details.
|
|
287
387
|
|
|
288
|
-
##
|
|
388
|
+
## Evaluation and Calibration
|
|
289
389
|
|
|
290
|
-
OpenCodeRAG
|
|
390
|
+
OpenCodeRAG tracks token usage, RAG injection overhead, and costs across sessions, so you can measure whether semantic retrieval actually saves tokens.
|
|
291
391
|
|
|
292
392
|
```bash
|
|
293
|
-
opencode-rag
|
|
393
|
+
opencode-rag eval:sessions # list sessions
|
|
394
|
+
opencode-rag eval:analyze <id> # detailed breakdown
|
|
395
|
+
opencode-rag eval:compare <A> <B> # side-by-side comparison
|
|
294
396
|
```
|
|
295
397
|
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
### MCP Tools
|
|
299
|
-
|
|
300
|
-
| Tool | Description |
|
|
301
|
-
|------|-------------|
|
|
302
|
-
| `search_semantic` | Vector + keyword hybrid search across the indexed codebase |
|
|
303
|
-
| `get_file_skeleton` | AST-based file outline (functions, classes, methods) |
|
|
304
|
-
| `find_usages` | Find all references to a symbol by name |
|
|
305
|
-
| `describe_image` | Describe an image file with the configured vision model (`imageDescription.onDemand` overrides apply; paths outside the workspace are allowed) |
|
|
306
|
-
| `make_decision` | Classify/route/score short text with the local tev1 decision model (only when `decision.enabled` is `true`) |
|
|
307
|
-
|
|
308
|
-
Clients can configure the MCP server manually, or `opencode-rag init` auto-registers it.
|
|
309
|
-
|
|
310
|
-
## Agent Discovery
|
|
311
|
-
|
|
312
|
-
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):
|
|
313
|
-
|
|
314
|
-
1. **Skeleton first** - `get_file_skeleton(filePath)` to orient in a file
|
|
315
|
-
2. **Find usages** - `find_usages(symbolName)` before editing any symbol
|
|
316
|
-
3. **Search** - `search_semantic(query)` to find relevant code
|
|
317
|
-
4. **Describe images** - `describe_image(filePath)` when context involves an image
|
|
318
|
-
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)
|
|
319
|
-
6. **Read** - use `read` on specific line ranges
|
|
320
|
-
7. **Edit** - make changes with full context
|
|
321
|
-
|
|
322
|
-
### Available Tools
|
|
398
|
+
Token counting uses tiktoken BPE (cl100k_base) for accurate code tokenization. See the [Evaluation documentation](doc/evaluation.md) for details.
|
|
323
399
|
|
|
324
|
-
|
|
325
|
-
|------|---------|-------------|
|
|
326
|
-
| `search_semantic` | General-purpose code retrieval | Before any code task when you haven't read the relevant code |
|
|
327
|
-
| `get_file_skeleton` | Quick file overview via AST | Before reading a large file to decide which sections matter |
|
|
328
|
-
| `find_usages` | Symbol reference search | **Before editing** any function, variable, or class |
|
|
329
|
-
| `describe_image` | Live image description via the configured vision model | When a user asks about a screenshot, diagram, or visual asset |
|
|
330
|
-
| `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 |
|
|
331
|
-
| `read` (optional) | RAG-enhanced file read | Full file contents with supplementary context chunks |
|
|
400
|
+
Retrieval quality has its own harness:
|
|
332
401
|
|
|
333
|
-
|
|
402
|
+
- `opencode-rag eval:gate` runs the labelled golden set and fails when Hit@5 / MRR / nDCG@10 drop below the documented floors.
|
|
403
|
+
- `opencode-rag eval:decide` measures tev1's accuracy, ECE, and Brier score on a labelled calibration set.
|
|
404
|
+
- `opencode-rag eval:tune` sweeps the retrieval fusion weights against the same golden set and reports the best configuration for your setup. The shipped `keywordWeight=0.4` is a default, not an optimum (on a code embedder it costs ~8 Hit@5 points) — measure it instead of guessing.
|
|
334
405
|
|
|
335
|
-
|
|
406
|
+
## Configuration
|
|
336
407
|
|
|
337
|
-
|
|
338
|
-
`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.
|
|
408
|
+
Settings live in JSON (no comments). The workspace file `.opencode/opencode-rag.json` is canonical; the global file `~/.config/opencode/opencode-rag.json` holds machine-wide settings (Shell Guard, provider choices) that every workspace inherits. Shown below are the shipped defaults:
|
|
339
409
|
|
|
340
|
-
|
|
341
|
-
|
|
410
|
+
```json
|
|
411
|
+
{
|
|
412
|
+
"embedding": { "provider": "ollama", "model": "qwen3-embedding:0.6b" },
|
|
413
|
+
"retrieval": {
|
|
414
|
+
"topK": 20,
|
|
415
|
+
"minScore": 0.35,
|
|
416
|
+
"hybridSearch": { "enabled": true, "keywordWeight": 0.4, "symbolKeywordWeight": 0.6 }
|
|
417
|
+
},
|
|
418
|
+
"shellGuard": { "enabled": false, "threshold": 0.5, "onError": "allow" },
|
|
419
|
+
"decision": { "enabled": false, "model": "tev1:4b" }
|
|
420
|
+
}
|
|
421
|
+
```
|
|
342
422
|
|
|
343
|
-
|
|
344
|
-
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).
|
|
423
|
+
The [Configuration reference](doc/configuration.md) documents every option — embedding, indexing, retrieval, description, image description, decision, shell guard, and plugin settings — and how the global and workspace layers merge.
|
|
345
424
|
|
|
346
|
-
|
|
425
|
+
## Documentation Index
|
|
347
426
|
|
|
348
|
-
|
|
427
|
+
| Document | Contents |
|
|
428
|
+
|---|---|
|
|
429
|
+
| [Architecture](doc/architecture.md) | Module design, data flow, tech stack |
|
|
430
|
+
| [Installation](doc/installation.md) | Full install guide, global setup, uninstall |
|
|
431
|
+
| [Configuration](doc/configuration.md) | All options: embedding, indexing, retrieval, description, image description, decision, shell guard, plugin |
|
|
432
|
+
| [Chunking](doc/chunking.md) | Language matrix, adding new chunkers, custom chunkers |
|
|
433
|
+
| [Embedding](doc/embedding.md) | Providers, model recommendations, proxy, dimension probing |
|
|
434
|
+
| [ClickHouse store](doc/clickhouse.md) | Central vector store backend: setup, epochs, ANN, multi-machine sync |
|
|
435
|
+
| [Retrieval](doc/retrieval.md) | Pipeline, hybrid search, score fusion, caching |
|
|
436
|
+
| [Plugin](doc/plugin.md) | OpenCode integration, tools, hooks, TUI, troubleshooting |
|
|
437
|
+
| [CLI Reference](doc/cli.md) | All commands, options, examples |
|
|
438
|
+
| [Web UI](doc/webui.md) | Dashboard, chunk browser, file explorer, compare view |
|
|
439
|
+
| [Evaluation](doc/evaluation.md) | Token analysis, session logging, benchmark runner, accuracy guide |
|
|
440
|
+
| [Development](doc/development.md) | Setup, testing, conventions, adding providers |
|
|
441
|
+
| [Troubleshooting](doc/troubleshooting.md) | Common issues, logging, debugging |
|
|
442
|
+
| [Roadmap](doc/roadmap.md) | Completed items, short/mid/long-term plans |
|
|
349
443
|
|
|
350
|
-
|
|
444
|
+
## Privacy and Security
|
|
351
445
|
|
|
352
|
-
|
|
353
|
-
opencode-rag eval:sessions # list sessions
|
|
354
|
-
opencode-rag eval:analyze <id> # detailed breakdown
|
|
355
|
-
opencode-rag eval:compare <A> <B> # side-by-side comparison
|
|
356
|
-
```
|
|
446
|
+
**100% local by default.** Embeddings are generated locally via Ollama, and the vector database stays in your project directory. **No source code or embeddings leave your machine** unless you explicitly configure a third-party API. The optional [Shell Guard](#shell-guard-optional) likewise sends command text only to the decision-model endpoint you configure (local Ollama or a local proxy).
|
|
357
447
|
|
|
358
|
-
|
|
448
|
+
Every quirk written to memory passes an immutable trust monitor that rejects destructive patterns, and the decision model is only ever asked about short excerpts you (or the agent) pass in.
|
|
359
449
|
|
|
360
|
-
|
|
450
|
+
## Limitations and Non-Goals
|
|
361
451
|
|
|
362
|
-
|
|
452
|
+
- **This README is the entry point, not the manual.** Deep dives live in [`doc/`](doc/); the project does not aim to duplicate API references here.
|
|
453
|
+
- **Retrieval quality depends on the embedding model.** Small CPU-friendly models trade accuracy for speed; measure with `eval:gate` and `eval:tune` rather than assuming a default.
|
|
454
|
+
- **Image descriptions need a vision model.** They are on by default; set `imageDescription.enabled: false` if you have none — it is the one feature that meaningfully wants a GPU to be pleasant.
|
|
455
|
+
- **Shell Guard costs one model call per shell command** (~200 ms warm) and fails open by default; it is a safety net, not a sandbox.
|
|
456
|
+
- **The decision model currently supports Ollama's `/v1/systemone` endpoint only.**
|
|
457
|
+
- **The ClickHouse backend is opt-in** and requires a running ClickHouse server; LanceDB is the default and needs no server.
|
|
363
458
|
|
|
364
|
-
##
|
|
459
|
+
## Contributing and Support
|
|
365
460
|
|
|
366
|
-
**
|
|
461
|
+
- **Development setup, conventions, and testing:** [doc/development.md](doc/development.md)
|
|
462
|
+
- **Troubleshooting and logging:** [doc/troubleshooting.md](doc/troubleshooting.md)
|
|
463
|
+
- **Bug reports and feature requests:** [GitHub Issues](https://github.com/MrDoe/OpenCodeRAG/issues)
|
|
464
|
+
- **Roadmap:** [doc/roadmap.md](doc/roadmap.md)
|
|
367
465
|
|
|
368
466
|
## License
|
|
369
467
|
|