opencode-rag

Code Navigation

ALWAYS use OpenCodeRAG tools before reading or editing:

• Search first — search_semantic(query) instead of grep/glob. Optional args: pathHints, languageHints, fileExtensions (e.g. [".ts"]), topK
• Skeleton before read — get_file_skeleton(filePath) then read specific lines
• Usages before edit — find_usages(symbolName) before modifying any symbol
• Images via describe — describe_image(filePath, systemPrompt?) — never read raw bytes

If no results, run opencode-rag index.

Architecture

Entry points: src/index.ts (library), src/plugin-entry.ts (OpenCode plugin), src/cli.ts (CLI), src/tui.ts (TUI), src/web/server.ts (Web UI).

Core modules: src/core/ (config, interfaces, manifest), src/chunker/ (AST chunking), src/embedder/ (Ollama/OpenAI/Cohere), src/describer/ (LLM descriptions), src/retriever/ (vector + keyword hybrid), src/vectorstore/ (LanceDB), src/opencode/ (plugin integration).

Full architecture: doc/architecture.md.

Known Gotchas

• npm install: use --legacy-peer-deps (LanceDB peer dep conflicts)
• LanceDB types: cast through unknown — rows as unknown as Record<string, unknown>[]
• LanceDB index metric: the IVF index on embedding must use distanceType: "cosine" to match searchInternal (default is l2, which makes every query log "Requested metric Cosine is incompatible" and fall back to brute-force). LanceDbStore.ensureCosineIndex() self-heals stale L2 indexes on first search. When replacing an index, use a single createIndex(..., replace: true, waitTimeoutSeconds) — a dropIndex + createIndex sequence races and fails with "Retryable commit conflict".
• LanceDB "partition N is empty, skipping" warnings: benign once per index build (IVF KMeans on duplicate/degenerate vectors). Constant spam = retrain churn from a store whose index commits never register (one new _indices/<uuid> dir per attempt). repairIndexMetricOnce guards: counts only index-version dirs WITH files (empty husks from version pruning never trip it), verifies post-createIndex registration via indexStats, gives up after 3 failed attempts per process; optimize() sweeps empty husk dirs, and rebuilds pass optimize({ skipIndex: true }) to temp-store mid-run optimizes so the index is built once at the end. Fix for a truly non-converging store: delete rag_db + reindex. Note: u64-near _versions/*.manifest names are NORMAL (counter starts at u64::MAX-1 and decrements) — not corruption.
• tree-sitter: WASM-only (no native). Parser is a class, Language is top-level, use Node not SyntaxNode
• Plugin types: @opencode-ai/plugin lives in .opencode/node_modules/, declared locally in src/types/opencode-plugin.d.ts
• Config loading: loadConfig() deep-merges per section (not recursive). CLI auto-detects ./opencode-rag.json and ./.opencode/rag.json
• Ollama responses: may return { embedding: number[] } or { embeddings: number[][] } — both accepted
• Quirk test: opencode-rag quirk test <text> checks if a quirk already exists in the store (semantic search). Returns match details or "not appended"
• Auto-capture quirks: three memory.* flags — passiveCapture (per-turn extraction), promptEnforcement (mandatory system prompt), sessionEndExtraction (full-transcript on session end). All off by default. Requires description.enabled: true (reuses description LLM for extraction).
• Auto-capture dedup: candidate quirks are deduped against existing quirks via lexical similarity (autoCaptureDedupThreshold, default 0.85) before being added.
• excludeDirs/excludeFiles matching (src/core/exclude.ts): plain names (no /, no glob chars) match basename at any depth; patterns with a separator are anchored to workspace root. Matching is case-insensitive. Uses minimatch (bundled TS types). walkFiles no longer auto-skips dotdirs — rely on excludeDirs config instead.
• noUncheckedIndexedAccess in tsconfig.json: array indexing returns string | undefined. Use for...of loops instead of indexed for in new code to avoid Object is possibly 'undefined' errors.
• watch.ts ignores both excludeDirs AND excludeFiles: createWatchIgnore uses both matchers — any excludeFiles pattern applies to file-watch ignore too.
• walkFiles signature changed: excludeDirs/excludeFiles params changed from Set<string> to ExcludeMatcher; rootDir param added. If you import walkFiles directly, update the call site or use scanWorkspaceFiles instead.
• Watcher runs once per workspace: createBackgroundIndexer claims {storePath}/watcher.lock (atomic O_EXCL create + PID liveness via process.kill(pid, 0)). Only ONE process runs the auto-index watcher per workspace; later claimants go dormant (no chokidar/scheduler/passes) and take over via a 60s unref'd re-check timer after the owner exits. CLI index --watch shares the same lock — if a plugin watcher already owns the workspace it warns and exits 0. Only the owner's close() releases the lock; stale/corrupt lock files are auto-reclaimed.