opencode-rag-plugin 2.11.2 → 2.12.1

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.
Files changed (50) hide show
  1. package/ReadMe.md +386 -222
  2. package/dist/cli/commands/backend-detect.d.ts +1 -1
  3. package/dist/cli/commands/backend-detect.js +1 -1
  4. package/dist/cli/commands/index.d.ts +0 -1
  5. package/dist/cli/commands/index.js +0 -1
  6. package/dist/cli/commands/setup.js +344 -85
  7. package/dist/cli/commands/{init-helpers.d.ts → workspace-helpers.d.ts} +10 -7
  8. package/dist/cli/commands/{init-helpers.js → workspace-helpers.js} +15 -62
  9. package/dist/cli/index.js +1 -2
  10. package/dist/cli/ollama.d.ts +12 -0
  11. package/dist/cli/ollama.js +26 -0
  12. package/dist/cli/prompt.d.ts +121 -0
  13. package/dist/cli/prompt.js +309 -0
  14. package/dist/cli/types.d.ts +31 -19
  15. package/dist/cli/wizard/apply.d.ts +60 -0
  16. package/dist/cli/wizard/apply.js +243 -0
  17. package/dist/cli/wizard/flow.d.ts +121 -0
  18. package/dist/cli/wizard/flow.js +904 -0
  19. package/dist/cli/wizard/model-catalog.d.ts +80 -0
  20. package/dist/cli/wizard/model-catalog.js +414 -0
  21. package/dist/cli/wizard/presets.d.ts +55 -0
  22. package/dist/cli/wizard/presets.js +70 -0
  23. package/dist/cli/wizard/repair.d.ts +54 -0
  24. package/dist/cli/wizard/repair.js +266 -0
  25. package/dist/cli/wizard/types.d.ts +99 -0
  26. package/dist/cli/wizard/types.js +5 -0
  27. package/dist/cli/workspace.d.ts +57 -0
  28. package/dist/cli/workspace.js +407 -0
  29. package/dist/cli.d.ts +1 -1
  30. package/dist/cli.js +1 -1
  31. package/dist/core/auto-scaffold.d.ts +21 -0
  32. package/dist/core/auto-scaffold.js +80 -0
  33. package/dist/core/config.d.ts +13 -2
  34. package/dist/core/config.js +13 -3
  35. package/dist/core/global-plugin.d.ts +48 -0
  36. package/dist/core/global-plugin.js +114 -0
  37. package/dist/core/provider-defaults.d.ts +2 -0
  38. package/dist/core/provider-defaults.js +4 -0
  39. package/dist/core/setup-runtime.js +40 -26
  40. package/dist/embedder/health.js +44 -2
  41. package/dist/eval/fast-index.js +1 -1
  42. package/dist/opencode/system-guidance.d.ts +1 -1
  43. package/dist/opencode/system-guidance.js +1 -1
  44. package/dist/tui.d.ts +11 -0
  45. package/dist/tui.js +12 -1
  46. package/dist/v2/v2-adapter.js +9 -0
  47. package/package.json +3 -2
  48. package/scripts/postinstall-setup.js +16 -0
  49. package/dist/cli/commands/init.d.ts +0 -51
  50. package/dist/cli/commands/init.js +0 -508
package/ReadMe.md CHANGED
@@ -1,138 +1,269 @@
1
- # OpenCodeRAG
1
+ # OpenCodeRAG
2
2
 
3
- OpenCodeRAG is a **local-first RAG plugin** for semantic code and image search, with a built-in **local decision model** for fast classification and an optional **Shell Guard** that vets shell commands before they run. 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.
4
-
5
- You don't need a dedicated GPU to run smaller embedding LLMs, as these models can still run performant on modern CPUs.
3
+ **A local-first toolkit that gives AI coding agents search, memory, judgment, and guardrails.**
6
4
 
7
5
  [![npm version](https://img.shields.io/npm/v/opencode-rag-plugin.svg)](https://www.npmjs.com/package/opencode-rag-plugin)
6
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
7
+
8
+ AI coding agents are capable, but they have four recurring weaknesses: they read whole files to find one function, they forget everything between sessions, they interrupt you with questions they could settle themselves, and they may run risky shell commands without a second opinion.
9
+
10
+ OpenCodeRAG addresses all these problems and more in one package:
11
+
12
+ - **Semantic Search**: retrieval tools that find relevant code parts by a rough description only
13
+ - **Persistent Memory**: vectorized memory, which keeps gotchas and decisions across sessions and automatically injects them into the context when necessary
14
+ - **Knowledge Base**: agents use and maintain a project wiki to understand the code base better
15
+ - **Basic Judgment**: a small local decision model that answers classification and routing questions
16
+ - **Guardrails**: shell guard, which evaluates shell commands for malignancy before they run
17
+ - **Image Description**: describes images with a local vision model for non-multimodal LLMs
18
+ - **Documentation Assistant**: maintains and adds code documentation where it is still missing or unclear
19
+
20
+ OpenCodeRAG is primarily built as an [OpenCode](https://opencode.ai) plugin. But it can also be run as a MCP server for other AI coding platforms or used as a standalone command-line tool. By default it works fully locally via Ollama, but it can also use OpenAI-compatible APIs.
21
+
22
+ No GPU is required, although it is recommended when using code and image descriptions. Smaller embedding models can still run fine on a modern CPU.
23
+
24
+ ---
25
+
26
+ ## Contents
27
+
28
+ - [What you get](#what-you-get)
29
+ - [Quick start](#quick-start)
30
+ - [How it works](#how-it-works)
31
+ - [Ways to use it](#ways-to-use-it)
32
+ - [Capabilities in detail](#capabilities-in-detail)
33
+ - [1. Semantic code search](#1-semantic-code-search)
34
+ - [2. Quirk memory](#2-quirk-memory)
35
+ - [3. Decision model](#3-decision-model)
36
+ - [4. Shell Guard](#4-shell-guard)
37
+ - [5. Documentation and wiki modes](#5-documentation-and-wiki-modes)
38
+ - [6. Image indexing](#6-image-indexing)
39
+ - [7. Web UI, evaluation, and calibration](#7-web-ui-evaluation-and-calibration)
40
+ - [Tool reference](#tool-reference)
41
+ - [Configuration](#configuration)
42
+ - [Privacy and security](#privacy-and-security)
43
+ - [Limitations](#limitations)
44
+ - [Documentation index](#documentation-index)
45
+ - [Contributing and support](#contributing-and-support)
46
+ - [License](#license)
47
+
48
+ ---
49
+
50
+ ## What you get
8
51
 
9
- > ⚠️ **Note:** Don't confuse this with the npm package `opencode-rag` (a discontinued project by a different author).
52
+ | Capability | What it does for your agent | On by default |
53
+ |---|---|:---:|
54
+ | **Search** | Finds the relevant code by meaning and by exact symbol name, instead of reading whole files | Yes |
55
+ | **Memory** | Remembers gotchas, decisions, and past tool failures across sessions | Yes |
56
+ | **Decisions** | Classifies, routes, and scores short text locally, without spending agent tokens | No |
57
+ | **Protection** | Checks every shell command for destructive or malicious intent before it runs | No |
58
+ | **Documentation** | Drives the agent to document undocumented code (`/doc`) and to maintain a project wiki (`/wiki`) | Wiki: yes, Doc: no |
59
+ | **Vision** | Makes screenshots and diagrams searchable through generated descriptions | Yes |
60
+ | **Measurement** | Tracks token use, retrieval quality, and decision accuracy, with a web dashboard | Tools, always available |
10
61
 
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 + risk category); clean commands run unchanged. Enable once, machine-wide — see [Shell Guard](#shell-guard-optional).
62
+ **Why it is built this way**
12
63
 
13
- ## Quick Start
64
+ - **Fewer tokens.** The agent gets the handful of relevant chunks, not entire files.
65
+ - **Search the way code is written.** AST-aware chunking keeps functions and classes intact. Hybrid vector and keyword search catches both meaning ("where is auth handled?") and exact names.
66
+ - **Local by default.** Embeddings, the vector store, and the optional decision model run on your machine. No source code leaves the workspace unless you configure a hosted provider.
67
+ - **Scales with the repository.** Incremental indexing and a background watcher keep the index current. An optional shared ClickHouse store supports large or multi-machine workspaces.
68
+
69
+ ---
70
+
71
+ ## Quick start
72
+
73
+ > **Package name:** only install `opencode-rag-plugin`. The npm package `opencode-rag` is an unrelated, discontinued project by a different author.
74
+
75
+ **Prerequisites:** Node.js v22+ and [Ollama](https://ollama.ai) (the default provider). OpenCode is optional; the CLI and MCP server work without it.
14
76
 
15
77
  ```bash
16
- # 1. Install globally (automatically sets up the OpenCode runtime)
78
+ # 1. Install the plugin and the CLI
17
79
  npm install -g opencode-rag-plugin
18
80
 
19
- # 2. One command per workspace - runtime check + workspace setup
81
+ # 2. Set up the runtime, the workspace, and your models
82
+ # (a short interactive wizard guides you through the configuration)
20
83
  cd /path/to/your/project
21
84
  opencode-rag setup
22
85
 
23
- # 3. Index your workspace
86
+ # 3. Build the index (may take a while)
24
87
  opencode-rag index
25
88
 
26
- # 4. CLI search test
89
+ # 4. Search from the terminal
27
90
  opencode-rag query "authentication middleware"
91
+ ```
92
+
93
+ Example output:
28
94
 
29
- # 5. Optional: vet every shell command (once per machine)
30
- mkdir -p ~/.config/opencode
31
- echo '{ "shellGuard": { "enabled": true } }' > ~/.config/opencode/opencode-rag.json
32
- # Requires the decision model: ollama pull tev1:0.8b
33
95
  ```
96
+ Querying: "authentication middleware"
97
+ Top-K: 10
98
+ Searching 1240 indexed chunks...
34
99
 
35
- > **Try it:** with Shell Guard enabled, `rm -rf ./dist` is flagged (`delete_files`, ~0.96 destructive) and prompts for confirmation, while `ls -la src` passes untouched (~0.2).
100
+ 3 result(s) in 41ms:
36
101
 
37
- `opencode-rag setup` installs/verifies the machine-level runtime and, when
38
- run inside a project, initializes the workspace (`.opencode/`, plugin entries,
39
- skill file, `.opencode/opencode-rag.json`) in one step. When the installed version is
40
- outdated, it fetches and installs the latest published version from npm.
41
- `opencode-rag init` remains available for re-syncing an already initialized
42
- workspace, and `opencode-rag update` upgrades to a newer release.
102
+ src/auth/middleware.ts:12-48
103
+ Score: 0.8123
104
+ ...
105
+ ```
43
106
 
44
- **Prerequisites:** Node.js v22+, [Ollama](https://ollama.ai) (default) or other LLM-hosters (OpenAI-, Google- or Anthropic-compatible).
107
+ Open OpenCode in the same directory and the agent can use the tools right away.
45
108
 
46
- `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`.
109
+ <details>
110
+ <summary><strong>What does <code>opencode-rag setup</code> do?</strong></summary>
47
111
 
48
- > **Contributors / developers:** Clone the repo and use `npm install --legacy-peer-deps; npm run build` — see [Development docs](doc/development.md).
112
+ It handles the whole onboarding in one command:
49
113
 
50
- ## Key Features
114
+ - installs or verifies the machine-level runtime in `~/.opencode/`
115
+ - scaffolds the current workspace (`.opencode/` config, plugin entries, skill files)
116
+ - on the first run, or with `--reconfigure`, starts a **model wizard** for the embedding, description, vision, and decision models
51
117
 
52
- | Feature | Description |
53
- |---|---|
54
- | **🛡️ Shell guard** | Optional **pre-execution vetting of every `shell`/`bash` command** by the local decision model — flagged commands ask for confirmation (with probabilities + risk category), clean commands run normally, fail-open by default. Machine-wide via the global config. [Details](#shell-guard-optional) |
55
- | **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 |
56
- | **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) |
57
- | **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)) |
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 |
76
-
77
- ## Shell Guard (Optional)
78
-
79
- 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.
118
+ A plain re-run only syncs the workspace files. The wizard is scriptable (`--yes`, `--provider`, `--base-url`, `--embedding-model`, `--description off`, and more), and `--skip-runtime` limits the run to the workspace. Use `opencode-rag update` to upgrade the runtime to a newer release.
119
+
120
+ `pnpm add -g`, `yarn global add`, and `bun add -g` work as drop-in replacements for npm. Setup and update detect which package manager owns the install.
121
+
122
+ </details>
123
+
124
+ ### Optional add-ons
125
+
126
+ These are off by default and can be enabled later:
127
+
128
+ | Add-on | Enable with | Requires |
129
+ |---|---|---|
130
+ | [Shell Guard](#4-shell-guard) | `shellGuard.enabled` or `setup --shell-guard on` | tev1 via Ollama ≥ 0.35 |
131
+ | [Decision model](#3-decision-model) | `decision.enabled` or `setup --decision on` | tev1 via Ollama ≥ 0.35 |
132
+ | [Documentation mode](#documentation-mode-doc) | `documentationMode.enabled` | nothing extra |
133
+ | [Shared ClickHouse Vector Database](doc/clickhouse.md) | `vectorStore.provider: "clickhouse"` or `setup --vector-store clickhouse` | a ClickHouse server |
134
+
135
+ Two features are **on** by default and worth disabling if they do not fit your setup: [image descriptions](#6-image-indexing) (`imageDescription.enabled`, needs a vision model) and [wiki mode](#wiki-mode-wiki) (`wikiMode.enabled`).
136
+
137
+ > **Contributors:** clone the repo and run `npm install --legacy-peer-deps; npm run build`. See the [development docs](doc/development.md).
138
+
139
+ ---
140
+
141
+ ## How it works
142
+
143
+ ```
144
+ Workspace files
145
+ │ tree-sitter chunking (AST-aware)
146
+ ▼
147
+ Chunks ─────► embeddings ─────► vector store (LanceDB by default)
148
+ │
149
+ └─────────► keyword index (TF×IDF)
150
+
151
+ Query ─► vector search + keyword search ─► weighted fusion ─► top-K chunks
152
+ ```
153
+
154
+ 1. **Index.** Files are split into semantic chunks, optionally described by a local LLM, embedded, and stored next to 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.
155
+ 2. **Retrieve.** The query is embedded and matched against both signals. The scores are fused and post-processed (deduplication, per-file chunk limits, adjacent-chunk merging) to fit the context window.
156
+ 3. **Use.** The agent calls `search_semantic`, `get_file_skeleton`, or `find_usages` instead of reading entire files.
157
+
158
+ The other capabilities build on the same foundation. For example, quirk memories are embedded and stored in the same vector store as your code.
159
+
160
+ ---
161
+
162
+ ## Ways to use it
163
+
164
+ | Mode | Best for | How to start |
165
+ |---|---|---|
166
+ | **OpenCode plugin** | Day-to-day agent work with the full feature set (hotkeys, memory, Shell Guard, `/doc`, `/wiki`) | `opencode-rag setup`, then open OpenCode |
167
+ | **MCP server** | Claude Desktop, Cursor, and any other MCP-compatible client | `opencode-rag mcp` |
168
+ | **CLI** | Scripts, CI, and manual exploration | `opencode-rag <command>` |
169
+
170
+ ### With OpenCode
171
+
172
+ - **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 added to the system prompt. It is skipped when nothing is indexed.
173
+ - **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.
174
+ - **Read override.** A normal `read` can return the file plus supplementary RAG chunks relevant to the surrounding work.
175
+ - **Settings.** Models, retrieval options, and keybindings are configurable in the TUI settings panel (`Alt+S` or `/rag-settings`).
176
+ - **`AGENTS.md` directive.** Workspace setup merges a tool-usage directive into `AGENTS.md` using sentinel markers.
177
+
178
+ ### With other MCP clients
179
+
180
+ ```bash
181
+ opencode-rag mcp
182
+ ```
183
+
184
+ The MCP server is only needed when an *external* client connects. Inside OpenCode the tools are registered in-process. 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.
185
+
186
+ ### From the CLI
187
+
188
+ ```bash
189
+ opencode-rag setup # install the runtime, scaffold the workspace, run the model wizard
190
+ opencode-rag index # build or update the index
191
+ opencode-rag query "..." # search from the terminal
192
+ opencode-rag status # index health and coverage
193
+ opencode-rag ui # open the web dashboard
194
+ ```
195
+
196
+ 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).
197
+
198
+ ---
199
+
200
+ ## Capabilities in detail
201
+
202
+ ### 1. Semantic code search
203
+
204
+ The core of the project. It answers natural-language queries with the most relevant code.
205
+
206
+ - **Languages and formats.** AST chunking for 26 languages via tree-sitter, plus documents (Markdown, LaTeX, PDF, DOCX, Excel) and images.
207
+ - **Hybrid search.** Vector similarity combined with TF×IDF keyword matching. The keyword index is repaired from the store whenever it drifts behind, so the keyword half never covers only part of the corpus.
208
+ - **Context optimization.** Deduplication, per-file chunk limits, and adjacent-chunk merging.
209
+ - **Configurable parsers.** Remap file extensions to any parser via `chunking.parsers` (for example `.c` → `cpp`). The override applies to chunking, `get_file_skeleton`, and read labels ([docs](doc/chunking.md#parser-overrides-per-extension-chunkingparsers)).
210
+ - **Alternate providers.** Embeddings via Ollama, OpenAI-compatible endpoints, or Cohere. Descriptions and vision via Anthropic, Google Gemini, or OpenAI-compatible endpoints.
211
+ - **Scale.** Incremental indexing, a background watcher, and automatic rebuild on corruption. The optional ClickHouse backend provides one shared index across machines and workspaces, with HNSW ANN, epoch rebuilds, and state sync ([docs](doc/clickhouse.md)).
212
+
213
+ ### 2. Quirk memory
214
+
215
+ Quirk memory gives the agent a **persistent, cross-session memory** of non-obvious facts: gotchas, preferences, decisions, and environment constraints. Quirks are embedded in the same vector store as your code and injected into the agent's context when their relevance clears a configurable threshold. The agent stops repeating the same mistake and accumulates project knowledge over time.
216
+
217
+ **Enabled by default.** Configure it in `opencode-rag.json`:
80
218
 
81
219
  ```json
82
220
  {
83
- "shellGuard": {
221
+ "memory": {
84
222
  "enabled": true,
85
- "threshold": 0.5,
86
- "timeoutMs": 10000,
87
- "onError": "allow"
223
+ "autoInject": true,
224
+ "minConfidence": 0.5,
225
+ "recallMinScore": 0.72,
226
+ "autoInjectMinScore": 0.75,
227
+ "autoInjectTopK": 1,
228
+ "autoInjectLatencyBudgetMs": 2000,
229
+ "injectOnToolError": true,
230
+ "autoCreateOnToolError": true,
231
+ "toolErrorCreateMaxPerSession": 2,
232
+ "decay": { "enabled": false, "halfLifeDays": 30 }
88
233
  }
89
234
  }
90
235
  ```
91
236
 
92
- - **Off by default** — enabling adds one local model call to the critical path of every shell command.
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"`.
237
+ **Three ways memory works**
99
238
 
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).
239
+ | Mechanism | What happens |
240
+ |---|---|
241
+ | **Auto-injection** | On every user message, quirks related to the query and the agent's last response are injected if their vector similarity reaches `autoInjectMinScore` (0.75). Each quirk is injected at most once per session. A latency budget (`autoInjectLatencyBudgetMs`, 2000 ms) keeps a slow embedder from blocking messages. |
242
+ | **Learning from failures** | When a tool call fails, the plugin looks for a matching quirk and injects it into the next request (`injectOnToolError`). If none exists, it writes one from a deterministic template built from the tool name and error text, with no LLM involved (`autoCreateOnToolError`). These quirks are tagged `tool-error`, kept for *future* sessions, and excluded from generic auto-injection. Creation is limited to 2 per session, with a 10-minute cooldown per error, and is skipped if a quirk for the same tool and cause already exists. |
243
+ | **Prevention** | Known durable failure patterns are injected into the system prompt *before* the model picks a tool (`toolErrorProactiveInject`), scoped to the tools the session can actually call. Transient causes such as rate limits are never warned about in advance. The first occurrence of a failure is unavoidable; every later session is warned up front. |
101
244
 
102
- ## Web UI
245
+ **Safety.** 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
246
 
104
- 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.
247
+ **Manual control from the CLI**
105
248
 
106
- ![OpenCodeRAG Web UI](doc/assets/webui-3d.png)
249
+ ```bash
250
+ opencode-rag quirk add "npm needs --legacy-peer-deps" --type gotcha --tag installation
251
+ opencode-rag quirk list
252
+ opencode-rag quirk update <id> --content "..." --type decision
253
+ opencode-rag quirk rm <id>
254
+ opencode-rag quirk lint # flag low-confidence, stale, or duplicate quirks
255
+ opencode-rag quirk test "npm needs --legacy-peer-deps"
256
+ ```
107
257
 
108
- Launch with `opencode-rag ui`. See [Web UI documentation](doc/webui.md) for details.
258
+ Manual `recall_quirks` calls use the looser `recallMinScore` (0.72). Raise it to 0.85 to keep unrelated quirks out of unrelated tasks. See the [plugin docs](doc/plugin.md#9-quirk-memory-experiential-memory) and the [CLI reference](doc/cli.md#quirk).
109
259
 
110
- ## Documentation
260
+ ### 3. Decision model
111
261
 
112
- | Document | Contents |
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 |
128
-
129
- ## Decision Model (`make_decision`)
130
-
131
- 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.
262
+ A small local model answers fast **classification, routing, policy, and scoring questions**, so the agent does not spend its own tokens on them. OpenCodeRAG uses 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 to 64 named questions and returns the chosen option with probabilities, typically in **40 to 150 ms warm**.
132
263
 
133
264
  | Question type | Use it for | Example |
134
265
  |---|---|---|
135
- | `choice` | Pick one of 2–24 options | "Which support intent is this?" → duplicate_charge / cancel / none |
266
+ | `choice` | Pick one of 2 to 24 options | "Which support intent is this?" → duplicate_charge / cancel / none |
136
267
  | `noul` | True/false probability | "Does the customer explicitly ask for a refund?" |
137
268
  | `score` | Place the input on a rubric | "How severe is this incident?" → cosmetic … critical |
138
269
 
@@ -150,20 +281,20 @@ One call, two questions:
150
281
  ```
151
282
 
152
283
  ```
153
- **Decision** — ollama/tev1:0.8b
284
+ Decision — ollama/tev1:0.8b
154
285
 
155
- - **intent** = `duplicate_charge` (confidence 0.97)
156
- - **refund** = true (p=0.96)
286
+ - intent = duplicate_charge (confidence 0.97)
287
+ - refund = true (p=0.96)
157
288
  ```
158
289
 
159
- **Prerequisites:** Ollama ≥ 0.35 and a pulled model:
290
+ **Setup**
160
291
 
161
292
  ```bash
162
- ollama pull tev1:0.8b # 812 MB, fast — good for quick labels and CI
163
- ollama pull tev1:4b # 4.4 GB, more accurate — recommended when scoring
293
+ ollama pull tev1:0.8b # 812 MB, fast: good for quick labels and CI
294
+ ollama pull tev1:4b # 4.4 GB, more accurate: recommended for scoring
164
295
  ```
165
296
 
166
- **Disabled by default** — opt in via `decision.enabled`:
297
+ Requires Ollama ≥ 0.35. **Disabled by default.** Opt in via `decision.enabled`:
167
298
 
168
299
  ```json
169
300
  {
@@ -177,194 +308,227 @@ ollama pull tev1:4b # 4.4 GB, more accurate — recommended when scoring
177
308
  }
178
309
  ```
179
310
 
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; don't use it for factual recall or as the only check for high-stakes decisions.
181
-
182
- **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
-
184
- `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).
185
-
186
- ## Image Indexing
311
+ **Using it well**
187
312
 
188
- 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").
313
+ - Always include a `none` / "cannot be determined" option.
314
+ - Keep `state` to the relevant excerpt (effective context is about 2k tokens).
315
+ - Treat `confidence < ~0.3` as undecided.
316
+ - Do not use it for factual recall, or as the only check for high-stakes decisions.
189
317
 
190
- **Supported providers:** Ollama, OpenAI, Anthropic, Google Gemini, and OpenCode Zen (`opencode`/`opencode-go`) compatible providers.
318
+ **Pre-ask routing (optional).** With `decision.routeBeforeAsking: true`, the agent is told to resolve option choices through `make_decision` before asking you. It proceeds on a confident answer and asks only when the model is undecided or the choice is a matter of preference. Off by default.
191
319
 
192
- **Disabled by default** — enable in `opencode-rag.json` to opt in (recommended for dedicated GPUs).
320
+ `opencode-rag decide` exposes the same engine from the CLI, and workspace setup creates a dedicated `make-decision` agent skill. See the [plugin docs](doc/plugin.md#make_decision) and the [configuration reference](doc/configuration.md#decision).
193
321
 
194
- ## Documentation Mode
322
+ ### 4. Shell Guard
195
323
 
196
- 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.
324
+ The same 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. If `p(destructive)` or `p(malicious)` reaches the threshold, the command is escalated to OpenCode's confirmation prompt together with the full verdict (probabilities plus a risk category). Otherwise it runs unchanged.
197
325
 
198
326
  ```json
199
327
  {
200
- "documentationMode": {
328
+ "shellGuard": {
201
329
  "enabled": true,
202
- "batchSize": 5
330
+ "threshold": 0.5,
331
+ "timeoutMs": 10000,
332
+ "onError": "allow"
203
333
  }
204
334
  }
205
335
  ```
206
336
 
207
- **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.
337
+ | Aspect | Behavior |
338
+ |---|---|
339
+ | **Default** | Off. Enabling it adds one local model call to every shell command. |
340
+ | **Speed** | A warm verdict takes about 200 to 230 ms. Example: `rm -rf ./dist` → 0.96 destructive; `ls -la src` → 0.23, allowed. |
341
+ | **On failure** | Fail-open by default (`onError: "allow"`): if the classifier is down or times out, the command runs and a warning is logged. Set `"ask"` to require confirmation instead. |
342
+ | **Cache** | Verdicts are cached for 10 minutes (256 entries). The key includes the provider and model, and cached probabilities are re-scored against the current threshold on every call. |
343
+ | **Scope** | Put the block in `~/.config/opencode/opencode-rag.json` to apply it to every workspace. A workspace config can still override or disable it. |
344
+ | **Live config** | Edits to `opencode-rag.json` apply without a restart. |
345
+ | **Backend** | Defaults to the `decision` section. Any `/v1/systemone` endpoint works, for example llama-swap with `"baseUrl": "http://localhost:11437", "model": "Clef-Flash"`. |
346
+
347
+ Every verdict is logged under `scope: shell.guard`, so you can tune the threshold against real commands. Shell Guard is a safety net, not a sandbox. See the [configuration reference](doc/configuration.md#shellguard) and the [plugin docs](doc/plugin.md#shell-guard-command-vetting).
208
348
 
209
- See [Plugin documentation](doc/plugin.md#5-documentation-mode--slash-command-doc) for details.
349
+ ### 5. Documentation and wiki modes
210
350
 
211
- ## Wiki Mode
351
+ Two optional modes turn the agent into a documentation maintainer.
212
352
 
213
- 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.
353
+ #### Documentation mode (`/doc`)
354
+
355
+ Off by default. When `documentationMode.enabled` is `true`, the plugin adds a `/doc` slash command that drives the agent to add JSDoc/TSDoc comments to undocumented source files. No agent tools are registered; it works entirely through the slash command and a documentation system prompt.
214
356
 
215
357
  ```json
216
- {
217
- "wikiMode": {
218
- "enabled": true
219
- }
220
- }
358
+ { "documentationMode": { "enabled": true, "batchSize": 5 } }
221
359
  ```
222
360
 
223
- **Slash commands:**
361
+ **Workflow**
362
+
363
+ 1. Type `/doc` to list all undocumented files, grouped by subdirectory.
364
+ 2. The agent picks a subdirectory and documents every public symbol, preserving existing comments and implementation code.
365
+ 3. Type `/doc src/auth/` to mark that subdirectory complete.
366
+
367
+ Progress is saved in `.opencode/rag_db/doc-mode-progress.json`, so later sessions resume where you left off. See the [plugin docs](doc/plugin.md#5-documentation-mode--slash-command-doc).
368
+
369
+ #### Wiki mode (`/wiki`)
370
+
371
+ On by default. When `wikiMode.enabled` is `true`, the plugin injects a wiki-maintainer system prompt. The agent builds and maintains a persistent knowledge wiki in `.opencode/wiki/`: interlinked markdown pages that synthesize knowledge from the codebase, docs, and conversations.
224
372
 
225
373
  | Command | Action |
226
374
  |---|---|
227
- | `/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 |
229
- | `/wiki lint` | Health-check for orphan pages, stale source refs, contradictions, missing cross-links |
375
+ | `/wiki` | Show wiki status (page count, subdirectories, index and log presence, latest log entry) |
376
+ | `/wiki seed` | Generate the initial wiki from the README, file structure, and code patterns |
377
+ | `/wiki lint` | Health-check for orphan pages, stale source references, contradictions, and missing cross-links |
230
378
 
231
- 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.
379
+ The agent maintains the pages during normal coding sessions; you do not write them yourself. The wiki lives in `.opencode/`, so it is git-trackable and every edit is a diff. See the [plugin docs](doc/plugin.md#6-wiki-mode--slash-command-wiki).
232
380
 
233
- See [Plugin documentation](doc/plugin.md#6-wiki-mode--slash-command-wiki) for the full protocol.
381
+ ### 6. Image indexing
234
382
 
235
- ## Quirk Memory
383
+ Image files (PNG, JPEG, WebP, and others) are sent to a vision-capable LLM, and the generated descriptions are stored as searchable chunks. Visual assets then become discoverable with natural-language queries such as "login screen screenshot" or "architecture diagram". The `describe_image` tool also lets an agent inspect an image on demand.
236
384
 
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.
385
+ - **Providers:** Ollama, OpenAI, Anthropic, Google Gemini, and OpenCode Zen (`opencode` / `opencode-go`) compatible providers.
386
+ - **On by default.** Set `imageDescription.enabled: false` to skip image files entirely. This is recommended if you have no vision model or no GPU.
238
387
 
239
- **Enabled by default.** Turn it on/off in `opencode-rag.json`:
388
+ ### 7. Web UI, evaluation, and calibration
240
389
 
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
- ```
258
-
259
- **Agent tools:**
390
+ **Web UI.** A browser dashboard for exploring the vector database: browse, visualize, and inspect chunks, and evaluate OpenCode sessions by retrieved chunks and consumed tokens. Launch it with `opencode-rag ui`. See the [Web UI docs](doc/webui.md).
260
391
 
261
- | Tool | Use when |
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 |
392
+ [![OpenCodeRAG Web UI](doc/assets/webui-3d.png)](doc/assets/webui-3d.png)
267
393
 
268
- **CLI — manage quirks directly:**
394
+ **Does it actually save tokens?** Session-level analysis compares RAG-on against RAG-off, using tiktoken BPE (`cl100k_base`) for code tokenization:
269
395
 
270
396
  ```bash
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
397
+ opencode-rag eval:sessions # list sessions
398
+ opencode-rag eval:analyze <id> # detailed breakdown
399
+ opencode-rag eval:compare <A> <B> # side-by-side comparison
280
400
  ```
281
401
 
282
- 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 raw vector similarity to that query clears `autoInjectMinScore` (default 0.75) - the same threshold for the user-message and system-prompt injections; `recallMinScore` (default 0.72) is the bar for manual `recall_quirks` calls. 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).
402
+ **Is retrieval good enough?** A separate harness measures quality:
283
403
 
284
- **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`, default on). If **no** quirk covers it, it writes one — `memory.autoCreateOnToolError` (default on) — using a deterministic template built from the tool name and the error text, so no LLM is involved. The new quirk is tagged `tool-error` and recorded for *future* sessions; it is deliberately excluded from the generic auto-injection above, 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 min), and it is suppressed when a quirk for the same tool and cause class already exists.
404
+ | Command | Purpose |
405
+ |---|---|
406
+ | `opencode-rag eval:gate` | Runs the labelled golden set and fails when Hit@5, MRR, or nDCG@10 drop below the documented floors |
407
+ | `opencode-rag eval:decide` | Measures the decision model's accuracy, ECE, and Brier score on a labelled calibration set |
408
+ | `opencode-rag eval:tune` | Sweeps the retrieval fusion weights against the golden set and reports the best configuration for your setup |
285
409
 
286
- **Prevention, not just learning.** The gotchas are also injected into the **system prompt before the model picks a tool** (`memory.toolErrorProactiveInject`, default on), scoped to the tools the session can actually call and to durable failures 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.
410
+ The shipped `keywordWeight=0.4` is a default, not an optimum (on a code embedder it costs about 8 Hit@5 points), so measure instead of guessing. See the [evaluation docs](doc/evaluation.md).
287
411
 
288
- ## MCP Server (Optional)
412
+ ---
289
413
 
290
- 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.).
414
+ ## Tool reference
291
415
 
292
- ```bash
293
- opencode-rag mcp
294
- ```
416
+ ### MCP tools (plugin and MCP server)
295
417
 
296
- > **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`).
418
+ Inside OpenCode the plugin registers these in-process. Over MCP they are served by `opencode-rag mcp`.
297
419
 
298
- ### MCP Tools
420
+ | Tool | What it does | When the agent uses it |
421
+ |---|---|---|
422
+ | `search_semantic` | Hybrid vector and keyword search over the indexed code | Before a code task, instead of reading whole files |
423
+ | `get_file_skeleton` | AST outline of a file (functions, classes, methods) | To orient in a large file before reading it |
424
+ | `find_usages` | Every reference to a symbol | Before editing a function, class, or variable |
425
+ | `describe_image` | Describes an image with the configured vision model | When the task involves a screenshot, diagram, or other asset |
426
+ | `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 |
299
427
 
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`) |
428
+ ### Plugin-only tools (OpenCode)
307
429
 
308
- Clients can configure the MCP server manually, or `opencode-rag init` auto-registers it.
430
+ Registered by the OpenCode plugin, not served over MCP.
309
431
 
310
- ## Agent Discovery
432
+ | Tool | What it does |
433
+ |---|---|
434
+ | `recall_quirks` | Recalls stored gotchas, preferences, and decisions from past sessions |
435
+ | `add_quirk` | Stores a new non-obvious fact, workaround, or convention |
436
+ | `update_quirk` | Corrects a stored quirk that is outdated or wrong |
437
+ | `delete_quirk` | Removes a quirk that is fixed, obsolete, or no longer applies |
311
438
 
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):
439
+ ### Slash commands and hotkeys (OpenCode)
313
440
 
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
441
+ Default hotkeys and slash commands:
321
442
 
322
- ### Available Tools
443
+ | Input | Action |
444
+ |---|---|
445
+ | `Ctrl+Enter` | Append a relevant file list to the prompt |
446
+ | `Ctrl+Alt+Enter` | Append full code chunks to the prompt |
447
+ | `/rag-settings` or `Alt+S` | Open the settings panel |
448
+ | `/doc` | Documentation mode (if enabled) |
449
+ | `/wiki`, `/wiki seed`, `/wiki lint` | Wiki mode |
323
450
 
324
- | Tool | Purpose | When to Use |
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 |
451
+ Hotkeys can be changed via /rag-settings.
332
452
 
333
- ## OpenCode Integration
453
+ ---
334
454
 
335
- When using OpenCode, the plugin enhances your agent with three discovery mechanisms:
455
+ ## Configuration
336
456
 
337
- ### 1. Skill-Based Discovery
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.
457
+ Settings are stored as JSON (no comments).
339
458
 
340
- ### 2. System Prompt Guidance
341
- 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.
459
+ | File | Purpose |
460
+ |---|---|
461
+ | `.opencode/opencode-rag.json` | Workspace config (canonical) |
462
+ | `~/.config/opencode/opencode-rag.json` | Machine-wide settings (Shell Guard, provider choices) inherited by every workspace |
342
463
 
343
- ### 3. On-Demand RAG Context (Ctrl+Enter / Ctrl+Alt+Enter)
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).
464
+ Shipped defaults:
465
+
466
+ ```json
467
+ {
468
+ "embedding": { "provider": "ollama", "model": "qwen3-embedding:0.6b" },
469
+ "retrieval": {
470
+ "topK": 20,
471
+ "minScore": 0.35,
472
+ "hybridSearch": { "enabled": true, "keywordWeight": 0.4, "symbolKeywordWeight": 0.6 }
473
+ },
474
+ "shellGuard": { "enabled": false, "threshold": 0.5, "onError": "allow" },
475
+ "decision": { "enabled": false, "model": "tev1:4b" }
476
+ }
477
+ ```
478
+
479
+ The [configuration reference](doc/configuration.md) documents every option (embedding, indexing, retrieval, description, image description, decision, Shell Guard, plugin) and how the global and workspace layers merge.
345
480
 
346
481
  ---
347
482
 
348
- ## Evaluation & Token Analysis
483
+ ## Privacy and security
349
484
 
350
- OpenCodeRAG tracks token usage, RAG injection overhead, and costs across sessions. Compare RAG-on vs RAG-off to measure whether semantic retrieval saves tokens.
485
+ - **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.
486
+ - **Shell Guard** sends command text only to the decision-model endpoint you configure (local Ollama or a local proxy).
487
+ - **Decision model** is only asked about short excerpts that you or the agent pass in.
488
+ - **Quirk memory** writes pass an immutable trust monitor that rejects destructive patterns.
351
489
 
352
- ```bash
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
- ```
490
+ ---
491
+
492
+ ## Limitations
357
493
 
358
- Token counting uses tiktoken BPE (cl100k_base) for accurate code tokenization. See [Evaluation documentation](doc/evaluation.md) for details.
494
+ - **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.
495
+ - **Image descriptions need a vision model.** This is a feature that meaningfully wants a GPU to be pleasant. Disable it with `imageDescription.enabled: false` if you have none.
496
+ - **Shell Guard costs one model call per shell command** (about 200 ms warm) and fails open by default. It is a safety net, not a sandbox.
497
+ - **The decision model supports only Ollama's `/v1/systemone` endpoint** for now.
498
+ - **ClickHouse is opt-in** and needs a running server. LanceDB is the default and needs no separate installation.
359
499
 
360
- Retrieval quality has its own harness: `opencode-rag eval:gate` runs the labelled golden set and fails when Hit@5 / MRR / nDCG@10 drop below the documented floors, and `opencode-rag eval:decide` measures tev1's accuracy, ECE, and Brier score on a labelled calibration set. `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), so measure it instead of guessing.
500
+ ---
501
+
502
+ ## Documentation index
503
+
504
+ This README is the entry point. Deep dives live in [`doc/`](doc).
505
+
506
+ | Document | Contents |
507
+ |---|---|
508
+ | [Architecture](doc/architecture.md) | Module design, data flow, tech stack |
509
+ | [Installation](doc/installation.md) | Full install guide, global setup, uninstall |
510
+ | [Configuration](doc/configuration.md) | All options |
511
+ | [Chunking](doc/chunking.md) | Language matrix, adding new chunkers, custom chunkers |
512
+ | [Embedding](doc/embedding.md) | Providers, model recommendations, proxy, dimension probing |
513
+ | [ClickHouse store](doc/clickhouse.md) | Central vector store: setup, epochs, ANN, multi-machine sync |
514
+ | [Retrieval](doc/retrieval.md) | Pipeline, hybrid search, score fusion, caching |
515
+ | [Plugin](doc/plugin.md) | OpenCode integration, tools, hooks, TUI, troubleshooting |
516
+ | [CLI reference](doc/cli.md) | All commands, options, examples |
517
+ | [Web UI](doc/webui.md) | Dashboard, chunk browser, file explorer, compare view |
518
+ | [Evaluation](doc/evaluation.md) | Token analysis, session logging, benchmark runner, accuracy guide |
519
+ | [Development](doc/development.md) | Setup, testing, conventions, adding providers |
520
+ | [Troubleshooting](doc/troubleshooting.md) | Common issues, logging, debugging |
521
+ | [Roadmap](doc/roadmap.md) | Completed items, short-, mid-, and long-term plans |
361
522
 
362
523
  ---
363
524
 
364
- ## Privacy & Security
525
+ ## Contributing and support
365
526
 
366
- **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. 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).
527
+ - **Development setup, conventions, testing:** [doc/development.md](doc/development.md)
528
+ - **Troubleshooting and logging:** [doc/troubleshooting.md](doc/troubleshooting.md)
529
+ - **Bugs and feature requests:** [GitHub Issues](https://github.com/MrDoe/OpenCodeRAG/issues)
530
+ - **Roadmap:** [doc/roadmap.md](doc/roadmap.md)
367
531
 
368
532
  ## License
369
533
 
370
- MIT
534
+ [MIT](LICENSE)