opencode-rag-plugin 1.19.5 → 1.20.0

package/dist/chunker/image.d.ts

@@ -18,7 +18,7 @@ export declare function getMimeType(ext: string): string;
  * OpenAI, Anthropic, or Google Gemini).
  */
 export interface ImageVisionProvider {
-    describeImage(imageBase64: string, mimeType: string, prompt: string, abort?: AbortSignal): Promise<string>;
+    describeImage(imageBase64: string, mimeType: string, prompt: string, systemPrompt?: string, abort?: AbortSignal): Promise<string>;
 }
 /**
  * Factory function that creates the appropriate {@link ImageVisionProvider}

package/dist/chunker/image.js

@@ -42,6 +42,7 @@ class OllamaImageVisionProvider {
     timeoutMs;
     think;
     numCtx;
+    keepAlive;
     proxy;
     constructor(config) {
         this.baseUrl = config.baseUrl.replace(/\/+$/, "");
@@ -49,22 +50,25 @@ class OllamaImageVisionProvider {
         this.timeoutMs = config.timeoutMs;
         this.think = config.think ?? false;
         this.numCtx = config.numCtx;
+        this.keepAlive = config.keepAlive;
         this.proxy = config.proxy;
     }
-    async describeImage(imageBase64, _mimeType, prompt, abort) {
+    async describeImage(imageBase64, _mimeType, prompt, systemPrompt, abort) {
+        const messages = [];
+        if (systemPrompt && systemPrompt.trim().length > 0) {
+            messages.push({ role: "system", content: systemPrompt });
+        }
+        messages.push({ role: "user", content: prompt, images: [imageBase64] });
         const body = {
             model: this.model,
-            messages: [
-                {
-                    role: "user",
-                    content: prompt,
-                    images: [imageBase64],
-                },
-            ],
+            messages,
             stream: false,
             think: this.think,
             options: { num_ctx: this.numCtx },
         };
+        if (this.keepAlive) {
+            body.keep_alive = this.keepAlive;
+        }
         let lastError;
         for (let attempt = 0; attempt <= VISION_RETRY_MAX; attempt++) {
             const response = await postJson(`${this.baseUrl}/chat`, body, {}, this.timeoutMs, this.proxy, abort);
@@ -109,22 +113,25 @@ class OpenAIImageVisionProvider {
         this.timeoutMs = config.timeoutMs;
         this.proxy = config.proxy;
     }
-    async describeImage(imageBase64, mimeType, prompt, abort) {
+    async describeImage(imageBase64, mimeType, prompt, systemPrompt, abort) {
         const url = `${this.baseUrl}${this.baseUrl.endsWith("/v1") ? "" : "/v1"}/chat/completions`;
-        const body = {
-            model: this.model,
-            messages: [
+        const messages = [];
+        if (systemPrompt && systemPrompt.trim().length > 0) {
+            messages.push({ role: "system", content: systemPrompt });
+        }
+        messages.push({
+            role: "user",
+            content: [
+                { type: "text", text: prompt },
                 {
-                    role: "user",
-                    content: [
-                        { type: "text", text: prompt },
-                        {
-                            type: "image_url",
-                            image_url: { url: `data:${mimeType};base64,${imageBase64}` },
-                        },
-                    ],
+                    type: "image_url",
+                    image_url: { url: `data:${mimeType};base64,${imageBase64}` },
                 },
             ],
+        });
+        const body = {
+            model: this.model,
+            messages,
             max_tokens: 2048,
         };
         const headers = {
@@ -177,7 +184,7 @@ class AnthropicImageVisionProvider {
         this.timeoutMs = config.timeoutMs;
         this.proxy = config.proxy;
     }
-    async describeImage(imageBase64, mimeType, prompt, abort) {
+    async describeImage(imageBase64, mimeType, prompt, systemPrompt, abort) {
         const body = {
             model: this.model,
             max_tokens: 2048,
@@ -194,6 +201,9 @@ class AnthropicImageVisionProvider {
                 },
             ],
         };
+        if (systemPrompt && systemPrompt.trim().length > 0) {
+            body.system = systemPrompt;
+        }
         const headers = {
             "x-api-key": this.apiKey,
             "anthropic-version": "2023-06-01",
@@ -243,7 +253,7 @@ class GeminiImageVisionProvider {
         this.timeoutMs = config.timeoutMs;
         this.proxy = config.proxy;
     }
-    async describeImage(imageBase64, mimeType, prompt, abort) {
+    async describeImage(imageBase64, mimeType, prompt, systemPrompt, abort) {
         const body = {
             contents: [
                 {
@@ -260,6 +270,9 @@ class GeminiImageVisionProvider {
                 },
             ],
         };
+        if (systemPrompt && systemPrompt.trim().length > 0) {
+            body.system_instruction = { parts: [{ text: systemPrompt }] };
+        }
         const headers = {
             "Content-Type": "application/json",
         };

package/dist/cli/commands/backend-detect.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @fileoverview Auto-detect the Ollama backend (CPU vs GPU) during `init` and
+ * pick embedding batch settings tuned for the detected backend.
+ */
+/**
+ * Auto-detect whether Ollama runs models on the GPU or on the CPU and return
+ * matching embedding batch tuning.
+ *
+ * Detection uses `GET /api/ps`: loaded models report `size_vram` (bytes
+ * resident in VRAM). `size_vram > 0` means the model is (at least partially)
+ * offloaded to the GPU. If no model is loaded yet, a minimal `/api/embed`
+ * warmup loads the default embedding model first.
+ *
+ * Tuning is derived from benchmarks (see quirk memory):
+ * - GPU:  batch 40 + concurrency 4 ≈ 86 texts/s (~97% of the ~88 texts/s ceiling)
+ * - CPU:  flat ~3.5 texts/s regardless of batch size → small batches (20) with
+ *         concurrency 1 keep each request fast and under the 4096-token context
+ * - unreachable/unknown: defaults (100 / 3 / 100)
+ */
+import { type ProxyConfig } from "../../core/config.js";
+/** Detected Ollama backend kind. */
+export type OllamaBackend = "gpu" | "cpu" | "unreachable" | "unknown";
+/** Embedding batch settings written into the generated config. */
+export interface IndexingTuning {
+    embedBatchSize: number;
+    embedConcurrency: number;
+    ollamaMaxBatchSize: number;
+}
+/** Result of the backend detection. */
+export interface OllamaBackendInfo {
+    backend: OllamaBackend;
+    /** Tuning to write into the generated config. */
+    tuning: IndexingTuning;
+    /** Human-readable summary for the init output. */
+    message: string;
+}
+interface PsModel {
+    name: string;
+    size_vram?: number;
+}
+/**
+ * Classify loaded Ollama models into a backend + tuning profile.
+ *
+ * Prefers the configured default embedding model when it is loaded, falling
+ * back to any loaded model (a loaded GPU model means the host has a working
+ * GPU that Ollama will also use for embeddings).
+ *
+ * @param models - The `models` array from `GET /api/ps`.
+ * @returns The backend info with the matching tuning profile.
+ */
+export declare function classifyOllamaModels(models: PsModel[]): OllamaBackendInfo;
+/**
+ * Detect the Ollama backend by probing `/api/ps`, warming up the default
+ * embedding model when nothing is loaded yet.
+ *
+ * @param baseUrl - Ollama API base URL (defaults to the config default).
+ * @param proxy - Optional proxy configuration.
+ * @returns Backend info; never throws.
+ */
+export declare function detectOllamaBackend(baseUrl?: string, proxy?: ProxyConfig): Promise<OllamaBackendInfo>;
+export {};

package/dist/cli/commands/backend-detect.js

@@ -0,0 +1,119 @@
+/**
+ * @fileoverview Auto-detect the Ollama backend (CPU vs GPU) during `init` and
+ * pick embedding batch settings tuned for the detected backend.
+ */
+/**
+ * Auto-detect whether Ollama runs models on the GPU or on the CPU and return
+ * matching embedding batch tuning.
+ *
+ * Detection uses `GET /api/ps`: loaded models report `size_vram` (bytes
+ * resident in VRAM). `size_vram > 0` means the model is (at least partially)
+ * offloaded to the GPU. If no model is loaded yet, a minimal `/api/embed`
+ * warmup loads the default embedding model first.
+ *
+ * Tuning is derived from benchmarks (see quirk memory):
+ * - GPU:  batch 40 + concurrency 4 ≈ 86 texts/s (~97% of the ~88 texts/s ceiling)
+ * - CPU:  flat ~3.5 texts/s regardless of batch size → small batches (20) with
+ *         concurrency 1 keep each request fast and under the 4096-token context
+ * - unreachable/unknown: defaults (100 / 3 / 100)
+ */
+import { DEFAULT_CONFIG } from "../../core/config.js";
+import { fetchWithProxy, postJson } from "../../embedder/http.js";
+/** Benchmarked optimum on a GPU-backed Ollama (RTX 4090, qwen3-embedding:0.6b). */
+const GPU_TUNING = {
+    embedBatchSize: 40,
+    embedConcurrency: 4,
+    ollamaMaxBatchSize: 40,
+};
+/** CPU-backed Ollama: throughput is flat, so keep batches small and sequential. */
+const CPU_TUNING = {
+    embedBatchSize: 20,
+    embedConcurrency: 1,
+    ollamaMaxBatchSize: 20,
+};
+/** Fallback when Ollama is unreachable or the backend cannot be determined. */
+const DEFAULT_TUNING = {
+    embedBatchSize: DEFAULT_CONFIG.indexing.embedBatchSize,
+    embedConcurrency: DEFAULT_CONFIG.indexing.embedConcurrency ?? 3,
+    ollamaMaxBatchSize: DEFAULT_CONFIG.indexing.ollamaMaxBatchSize ?? 100,
+};
+/**
+ * Classify loaded Ollama models into a backend + tuning profile.
+ *
+ * Prefers the configured default embedding model when it is loaded, falling
+ * back to any loaded model (a loaded GPU model means the host has a working
+ * GPU that Ollama will also use for embeddings).
+ *
+ * @param models - The `models` array from `GET /api/ps`.
+ * @returns The backend info with the matching tuning profile.
+ */
+export function classifyOllamaModels(models) {
+    if (!models || models.length === 0) {
+        return {
+            backend: "unknown",
+            tuning: DEFAULT_TUNING,
+            message: "Could not determine the Ollama backend (no models loaded) — using default batch settings.",
+        };
+    }
+    const embedModel = DEFAULT_CONFIG.embedding.model;
+    const probe = models.find((m) => m.name === embedModel) ?? models[0];
+    const onGpu = probe ? (probe.size_vram ?? 0) > 0 : false;
+    if (onGpu) {
+        return {
+            backend: "gpu",
+            tuning: GPU_TUNING,
+            message: `Ollama detected on GPU — tuned embedding for batch 40 / concurrency 4 (${(probe?.size_vram ?? 0) / (1024 * 1024) | 0} MiB in VRAM).`,
+        };
+    }
+    return {
+        backend: "cpu",
+        tuning: CPU_TUNING,
+        message: "Ollama detected on CPU — tuned embedding for batch 20 / concurrency 1.",
+    };
+}
+/** Fetch `GET /api/ps`, returning null when Ollama is unreachable or errors. */
+async function getOllamaPs(baseUrl, proxy) {
+    const url = `${baseUrl.replace(/\/+$/, "")}/ps`;
+    try {
+        const res = await fetchWithProxy(url, { method: "GET", signal: AbortSignal.timeout(3000) }, proxy);
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        return data.models ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Detect the Ollama backend by probing `/api/ps`, warming up the default
+ * embedding model when nothing is loaded yet.
+ *
+ * @param baseUrl - Ollama API base URL (defaults to the config default).
+ * @param proxy - Optional proxy configuration.
+ * @returns Backend info; never throws.
+ */
+export async function detectOllamaBackend(baseUrl = DEFAULT_CONFIG.embedding.baseUrl, proxy) {
+    let models = await getOllamaPs(baseUrl, proxy);
+    if (models === null) {
+        return {
+            backend: "unreachable",
+            tuning: DEFAULT_TUNING,
+            message: "Ollama not reachable — using default batch settings.",
+        };
+    }
+    if (models.length === 0) {
+        // Nothing loaded yet: a minimal embed request loads the default
+        // embedding model so /api/ps can report its backend.
+        const embedUrl = `${baseUrl.replace(/\/+$/, "")}/embed`;
+        try {
+            await postJson(embedUrl, { model: DEFAULT_CONFIG.embedding.model, input: "warmup" }, {}, 15000, proxy);
+        }
+        catch {
+            // Model missing or request failed — classification will stay unknown.
+        }
+        models = (await getOllamaPs(baseUrl, proxy)) ?? [];
+    }
+    return classifyOllamaModels(models);
+}
+//# sourceMappingURL=backend-detect.js.map

package/dist/cli/commands/describe-image.js

@@ -22,6 +22,7 @@ export function registerDescribeImageCommand(program) {
         .description("Describe an image file using a vision model")
         .argument("<filePath>", "path to image file")
         .option("-c, --config <path>", "path to config file")
+        .option("-s, --system-prompt <text>", "optional system prompt to steer the description toward specific features")
         .action(async (filePath, options) => {
         try {
             const cwd = process.cwd();
@@ -56,7 +57,7 @@ export function registerDescribeImageCommand(program) {
             const sized = maxDimension > 0 ? await resizeImage(buffer, resolvedPath, maxDimension) : buffer;
             const b64 = sized.toString("base64");
             const provider = createImageVisionProvider(imageDescriptionConfig);
-            const description = await provider.describeImage(b64, mimeType, imageDescriptionConfig.prompt);
+            const description = await provider.describeImage(b64, mimeType, imageDescriptionConfig.prompt, options.systemPrompt);
             logCliInfo(logFilePath, "describe-image", `\n${c.desc(description)}\n`);
             await cleanupContext(ctx);
         }

package/dist/cli/commands/index-command.js

@@ -13,6 +13,7 @@ import readline from "node:readline";
 import chokidar from "chokidar";
 import { appendDebugLog } from "../../core/fileLogger.js";
 import { createWatchPassScheduler, createWatchIgnore, runIndexPass, } from "../../indexer.js";
+import { tryAcquireWatcherLock, releaseWatcherLock } from "../../watcher.js";
 import { c, resolveCliContext, cleanupContext, logCliError, logCliInfo, logIndexSummary, formatDuration, } from "../format.js";
 /**
  * Build a logger that suppresses console output when watchTriggered is true.
@@ -129,6 +130,15 @@ export function registerIndexCommand(program) {
                 await cleanupContext(ctx);
                 process.exit(sigReceived ? 130 : 0);
             }
+            // Only one watcher may run per workspace — a background auto-indexer
+            // in an OpenCode session (or another `index --watch`) may already own
+            // this store. The initial pass above still ran; just don't start a
+            // duplicate watcher.
+            if (!tryAcquireWatcherLock(storePath)) {
+                logCliInfo(logFilePath, "index", c.warn("Another watcher is already running for this workspace (e.g. an OpenCode session with auto-index enabled) — not starting a second one. The index is up to date."));
+                await cleanupContext(ctx);
+                process.exit(0);
+            }
             logCliInfo(logFilePath, "index", `\n${c.heading("Watching for changes...")}`);
             const scheduler = createWatchPassScheduler(async (changedPaths) => { await runPass(true, undefined, changedPaths); }, (error) => {
                 const message = error.message || String(error);
@@ -154,6 +164,7 @@ export function registerIndexCommand(program) {
                     watcher.close(),
                     new Promise((r) => setTimeout(r, 5000)),
                 ]);
+                releaseWatcherLock(storePath);
                 await cleanupContext(ctx);
                 process.exit(0);
             };

package/dist/cli/commands/init-helpers.d.ts

@@ -6,6 +6,7 @@
  * dependency installation, and gitignore merging.
  */
 import type { PackageMetadata } from "../types.js";
+import type { IndexingTuning } from "./backend-detect.js";
 /**
  * Build the workspace-local `.opencode/package.json` content.
  *
@@ -115,6 +116,8 @@ export declare function installPluginFromGlobal(opencodeDir: string, packageName
 /**
  * Generate the default `opencode-rag.json` configuration content.
  *
+ * @param tuning - Optional embedding batch tuning (auto-detected from the
+ *   Ollama backend). Falls back to `DEFAULT_CONFIG` for any omitted field.
  * @returns A pretty-printed JSON string with all default configuration values.
  */
-export declare function generateDefaultConfigJson(): string;
+export declare function generateDefaultConfigJson(tuning?: Partial<IndexingTuning>): string;

package/dist/cli/commands/init-helpers.js

@@ -165,7 +165,7 @@ export function generateSkillFile() {
         "2. User mentions a file path → `get_file_skeleton(filePath)` THEN `read` on specific lines",
         "3. User mentions a function/class/variable to edit → `find_usages(symbolName)` THEN `search_semantic` THEN `edit`",
         "4. User asks a code question → `search_semantic` to gather context before answering",
-        "5. User asks about an image or visual asset → `describe_image(filePath)` to retrieve its generated description, then optionally `search_semantic` for related code",
+        "5. User asks about an image or visual asset → `describe_image(filePath)` (optionally pass `systemPrompt` to focus on specific features) to retrieve its generated description, then optionally `search_semantic` for related code",
         "6. You encounter an error or need a known pitfall → `recall_quirks(query)`",
         "7. You discover a non-obvious fact or workaround → `add_quirk(content)` to persist it",
         "8. A recalled quirk is outdated or wrong → `update_quirk(id, ...)` to fix it, or `delete_quirk(id)` if it no longer applies",
@@ -188,7 +188,7 @@ export function generateSkillFile() {
         "1. **Skeleton first** — call `get_file_skeleton(filePath)` to see structure",
         "2. **Find usages** — call `find_usages(symbolName)` before modifying any symbol",
         "3. **Search** — call `search_semantic(query)` to find relevant code",
-        "4. **Describe images** — call `describe_image(filePath)` when context involves an image file",
+        "4. **Describe images** — call `describe_image(filePath)` when context involves an image file (pass `systemPrompt` to focus on specific features)",
         "5. **Read** — use the `read` tool on specific line ranges identified above",
         "6. **Edit** — now you have full context to make safe changes",
         "",
@@ -205,7 +205,7 @@ export function generateSkillFile() {
         "- `search_semantic`: `query` (req), `pathHints?`, `languageHints?`, `topK?`",
         "- `get_file_skeleton`: `filePath` (req)",
         "- `find_usages`: `symbolName` (req), `pathHint?`, `topK?`",
-        "- `describe_image`: `filePath` (req)",
+        "- `describe_image`: `filePath` (req), `systemPrompt?`",
         "- `recall_quirks`: `query` (req), `topK?`, `quirkType?`, `tags?`",
         "- `add_quirk`: `content` (req), `quirkType?`, `tags?`, `sourceRef?`",
         "- `update_quirk`: `id` (req) + at least one of `content?`, `quirkType?`, `tags?`, `confidence?`, `sourceRef?`",
@@ -216,6 +216,7 @@ export function generateSkillFile() {
         "- Use `pathHints` to narrow searches to specific directories",
         "- Use `languageHints` to filter by file type",
         "- `find_usages` is essential before refactoring — it shows every reference",
+        "- Pass `systemPrompt` to `describe_image` when you need specific details (e.g. `\"focus on the chart's axes and values\"`)",
         "- If no results appear, the workspace may not be indexed yet — run `opencode-rag index`",
         "- Image descriptions are generated at index time using the configured vision provider; ensure `imageDescription` is configured in `opencode-rag.json` if your project includes images",
         "",
@@ -414,9 +415,11 @@ export async function installPluginFromGlobal(opencodeDir, packageName, skipInst
 /**
  * Generate the default `opencode-rag.json` configuration content.
  *
+ * @param tuning - Optional embedding batch tuning (auto-detected from the
+ *   Ollama backend). Falls back to `DEFAULT_CONFIG` for any omitted field.
  * @returns A pretty-printed JSON string with all default configuration values.
  */
-export function generateDefaultConfigJson() {
+export function generateDefaultConfigJson(tuning) {
     return JSON.stringify({
         embedding: {
             provider: DEFAULT_CONFIG.embedding.provider,
@@ -430,7 +433,9 @@ export function generateDefaultConfigJson() {
             chunkOverlap: DEFAULT_CONFIG.indexing.chunkOverlap,
             minFileSizeBytes: DEFAULT_CONFIG.indexing.minFileSizeBytes,
             concurrency: DEFAULT_CONFIG.indexing.concurrency,
-            embedBatchSize: DEFAULT_CONFIG.indexing.embedBatchSize,
+            embedBatchSize: tuning?.embedBatchSize ?? DEFAULT_CONFIG.indexing.embedBatchSize,
+            embedConcurrency: tuning?.embedConcurrency ?? DEFAULT_CONFIG.indexing.embedConcurrency ?? 3,
+            ollamaMaxBatchSize: tuning?.ollamaMaxBatchSize ?? DEFAULT_CONFIG.indexing.ollamaMaxBatchSize ?? 100,
         },
         vectorStore: {
             path: DEFAULT_CONFIG.vectorStore.path,

package/dist/cli/commands/init.js

@@ -17,6 +17,7 @@ import { destroyAllPooledConnections } from "../../embedder/http.js";
 import { c } from "../format.js";
 import { getPackageMetadata, readJsonObject, writeJsonFile } from "../helpers.js";
 import { buildOpencodeConfig, buildWorkspacePackageJson, generateDefaultConfigJson, generateSkillFile, generateWorkspacePluginFile, generateWorkspaceTuiPluginFile, installPluginFromGlobal, mergeAgentsMdContent, mergeGitignoreContent, } from "./init-helpers.js";
+import { detectOllamaBackend } from "./backend-detect.js";
 /**
  * Register the `init` command on the given Commander program.
  *
@@ -29,7 +30,14 @@ import { buildOpencodeConfig, buildWorkspacePackageJson, generateDefaultConfigJs
 export function registerInitCommand(program) {
     program
         .command("init")
-        .description("Configure the current workspace for OpenCodeRAG")
+        .description("Configure this workspace (files + auto-tuned opencode-rag.json)")
+        .addHelpText("after", "\nUse cases:\n" +
+        "  - First-time workspace setup: creates .opencode/, the RAG skill file, AGENTS.md\n" +
+        "    guidance, and opencode-rag.json with embedding batches auto-detected for the\n" +
+        "    Ollama backend (GPU vs CPU).\n" +
+        "  - Re-running in an existing workspace: re-syncs plugin/skill files and keeps the\n" +
+        "    existing opencode-rag.json (overwriting requires interactive confirmation).\n" +
+        "\nWorkspace-level step — run AFTER 'opencode-rag setup' on this machine, then 'opencode-rag index'.\n")
         .option("-f, --force", "overwrite existing files")
         .option("--skip-install", "skip installing workspace-local plugin dependencies")
         .option("--skip-health-check", "skip provider connectivity and model availability check")
@@ -189,8 +197,27 @@ export function registerInitCommand(program) {
                 console.log(`  ${c.exists("Exists:")}   .opencode/package.json`);
             }
             const configExists = existsSync(configPath);
+            // Detect the Ollama backend (CPU vs GPU) lazily — only when we are
+            // actually about to write a config — and tune embedding batches for it.
+            let detectedTuning;
+            const configContent = async () => {
+                if (!detectedTuning) {
+                    try {
+                        const info = await detectOllamaBackend();
+                        detectedTuning = info.tuning;
+                        const icon = info.backend === "gpu" ? c.success("GPU:") :
+                            info.backend === "cpu" ? c.warn("CPU:") :
+                                c.dim("Backend:");
+                        console.log(`  ${icon} ${info.message}`);
+                    }
+                    catch {
+                        detectedTuning = undefined;
+                    }
+                }
+                return generateDefaultConfigJson(detectedTuning);
+            };
             if (!configExists) {
-                writeFileSync(configPath, generateDefaultConfigJson(), "utf-8");
+                writeFileSync(configPath, await configContent(), "utf-8");
                 console.log(`  ${c.created("Created:")} opencode-rag.json`);
             }
             else {
@@ -208,7 +235,7 @@ export function registerInitCommand(program) {
                 if (overwrite) {
                     copyFileSync(configPath, `${configPath}.bak`);
                     console.log(`  ${c.dim("Backup:")}        opencode-rag.json.bak`);
-                    writeFileSync(configPath, generateDefaultConfigJson(), "utf-8");
+                    writeFileSync(configPath, await configContent(), "utf-8");
                     console.log(`  ${c.updated("Updated:")}  opencode-rag.json`);
                 }
                 else {

package/dist/cli/commands/setup.js

@@ -36,7 +36,13 @@ function checkOpenCodeRunning() {
 export function registerSetupCommand(program) {
     program
         .command("setup")
-        .description("Set up the OpenCodeRAG runtime (~/.opencode/) for OpenCode plugin discovery")
+        .description("Install/update the OpenCodeRAG runtime once per machine")
+        .addHelpText("after", "\nUse cases:\n" +
+        "  - First-time install: run once per machine to install the plugin runtime\n" +
+        "    into ~/.opencode/ so OpenCode can discover the RAG plugin.\n" +
+        "  - Updating: re-sync the runtime to the published plugin version.\n" +
+        "  - Troubleshooting: use --check to inspect the runtime, or --force to reinstall.\n" +
+        "\nMachine-level step — run BEFORE 'opencode-rag init' (init configures each workspace).\n")
         .option("--uninstall", "remove the runtime and cleanup")
         .option("-f, --force", "force re-setup even if up-to-date")
         .option("--check", "check whether the runtime is correctly installed")

package/dist/cli/types.d.ts

@@ -20,6 +20,8 @@ export interface CliOptions {
     explain?: boolean;
     /** Skip confirmation prompts for destructive operations. */
     yes?: boolean;
+    /** Optional system prompt to steer an image description toward specific features. */
+    systemPrompt?: string;
 }
 /** Options for the `init` command. */
 export interface InitOptions {

package/dist/core/config.d.ts

@@ -54,7 +54,18 @@ export interface DescriptionConfig {
     proxy?: ProxyConfig;
     /** System prompt instructing the LLM how to describe code. */
     systemPrompt: string;
-    /** Maximum chunks per batch request. */
+    /**
+     * EXPERIMENTAL: enable multi-chunk batch description requests (Ollama
+     * provider only). Off by default — each chunk is described with its own
+     * request. When enabled, up to `batchMaxChunks` chunks share one request
+     * using ordinal labels ([CHUNK 1] ... reply "1: <desc>"); small models can
+     * mangle the structured output, so batches that fail to parse fall back to
+     * individual requests and batching auto-disables after 2 consecutive
+     * failures. Part of the description manifest fingerprint — toggling it
+     * re-describes files.
+     */
+    batchEnabled?: boolean;
+    /** Maximum chunks per batch request. Only applies when `batchEnabled` is true. */
     batchMaxChunks?: number;
     /** Timeout per batch request in milliseconds. */
     batchTimeoutMs?: number;
@@ -68,6 +79,8 @@ export interface DescriptionConfig {
     think?: boolean;
     /** Context window size for the LLM. */
     numCtx?: number;
+    /** Ollama keep_alive value (e.g. "-1" for keep-in-memory) sent with /api/chat requests. */
+    keepAlive?: string;
     /** Maximum content characters sent to the LLM. Chunks exceeding this use fallback descriptions. */
     maxContentChars?: number;
 }
@@ -91,6 +104,8 @@ export interface ImageDescriptionConfig {
     think?: boolean;
     /** Context window size. */
     numCtx?: number;
+    /** Ollama keep_alive value (e.g. "-1" for keep-in-memory) sent with /api/chat requests. */
+    keepAlive?: string;
     /** Proxy configuration. */
     proxy?: ProxyConfig;
     /** Maximum image dimension (pixels) — larger images are resized before sending. */
@@ -220,6 +235,8 @@ export interface RagConfig {
         queryPrefix?: string;
         /** Cached embedding vector dimension. Probed once on first startup, then persisted to config. */
         vectorDimension?: number;
+        /** Ollama keep_alive value (e.g. "-1" for keep-in-memory) sent with /api/embed requests. */
+        keepAlive?: string;
     };
     /** Indexing pipeline controls: what to index, concurrency, batch sizes. */
     indexing: {
@@ -268,6 +285,15 @@ export interface RagConfig {
          * @default 1_048_576 (1 MB)
          */
         maxSvgSizeBytes?: number;
+        /**
+         * Run vector-store compaction + version pruning every N windows during a
+         * long index pass. LanceDB keeps every committed version on disk, so
+         * without periodic maintenance the store phase slows down as the index
+         * grows (version-manifest accumulation). 0 disables mid-run optimization
+         * (the store is still optimized once at the end of a pass).
+         * @default 8
+         */
+        optimizeIntervalWindows?: number;
     };
     /** Vector storage backend configuration. */
     vectorStore: {

package/dist/core/config.js

@@ -115,9 +115,10 @@ export const DEFAULT_CONFIG = {
         concurrency: 8,
         embedBatchSize: 100,
         embedConcurrency: 3,
-        ollamaMaxBatchSize: 500,
+        ollamaMaxBatchSize: 100,
         descriptionConcurrency: 4,
         maxSvgSizeBytes: 1_048_576,
+        optimizeIntervalWindows: 8,
     },
     vectorStore: {
         path: "./.opencode/rag_db",
@@ -169,7 +170,10 @@ export const DEFAULT_CONFIG = {
         think: false,
         numCtx: 4096,
         timeoutMs: 60000,
-        systemPrompt: "Describe this code in 2-3 sentences: purpose, key concepts, inputs/outputs, and dependencies. No code repetition.",
+        systemPrompt: "Describe this code in ONE concise sentence (max 20 words): purpose, key inputs/outputs. No code repetition.",
+        batchEnabled: false,
+        batchMaxChunks: 25,
+        batchTimeoutMs: 120000,
         batchConcurrency: 1,
         retryMax: 3,
         retryBaseDelayMs: 1000,
@@ -427,6 +431,10 @@ export function validateConfig(config) {
         if (config.description.timeoutMs != null && config.description.timeoutMs <= 0) {
             warnings.push("description.timeoutMs must be > 0");
         }
+        if (config.description.batchEnabled === true) {
+            warnings.push("description.batchEnabled is EXPERIMENTAL — batching several chunks into one LLM request (Ollama only) " +
+                "is unreliable on small models; disable it if descriptions look wrong");
+        }
     }
     if (config.imageDescription) {
         if (config.imageDescription.enabled) {