@khivi/opencode-codebase-index 0.5.2 → 0.5.3

package/README.md

@@ -1,658 +1,197 @@
-# opencode-codebase-index
+# @khivi/opencode-codebase-index
 
-[![npm version](https://img.shields.io/npm/v/opencode-codebase-index.svg)](https://www.npmjs.com/package/opencode-codebase-index)
+[![npm version](https://img.shields.io/npm/v/@khivi/opencode-codebase-index.svg)](https://www.npmjs.com/package/@khivi/opencode-codebase-index)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Downloads](https://img.shields.io/npm/dm/opencode-codebase-index.svg)](https://www.npmjs.com/package/opencode-codebase-index)
-[![Build Status](https://img.shields.io/github/actions/workflow/status/Helweg/opencode-codebase-index/ci.yml?branch=main)](https://github.com/Helweg/opencode-codebase-index/actions)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
 
-> **Stop grepping for concepts. Start searching for meaning.**
-
-**opencode-codebase-index** brings semantic understanding to your [OpenCode](https://opencode.ai) workflow — and now to any MCP-compatible client like Cursor, Claude Code, and Windsurf. Instead of guessing function names or grepping for keywords, ask your codebase questions in plain English.
-
-## 🚀 Why Use This?
-
-- 🧠 **Semantic Search**: Finds "user authentication" logic even if the function is named `check_creds`.
-- ⚡ **Blazing Fast Indexing**: Powered by a Rust native module using `tree-sitter` and `usearch`. Incremental updates take milliseconds.
-- 🌿 **Branch-Aware**: Seamlessly handles git branch switches — reuses embeddings, filters stale results.
-- 🔒 **Privacy Focused**: Your vector index is stored locally in your project.
-- 🔌 **Model Agnostic**: Works out-of-the-box with GitHub Copilot, OpenAI, Gemini, or local Ollama models.
-- 🌐 **MCP Server**: Use with Cursor, Claude Code, Windsurf, or any MCP-compatible client — index once, search from anywhere.
-
-## ⚡ Quick Start
-
-1. **Install the plugin**
-   ```bash
-   npm install opencode-codebase-index
-   ```
-
-2. **Add to `opencode.json`**
-   ```json
-   {
-     "plugin": ["opencode-codebase-index"]
-   }
-   ```
-
-3. **Index your codebase**
-   Run `/index` or ask the agent to index your codebase. This only needs to be done once — subsequent updates are incremental.
-
-4. **Start Searching**
-   Ask:
-   > "Find the function that handles credit card validation errors"
-
-## 🌐 MCP Server (Cursor, Claude Code, Windsurf, etc.)
-
-Use the same semantic search from any MCP-compatible client. Index once, search from anywhere.
-
-1. **Install dependencies**
-   ```bash
-   npm install opencode-codebase-index @modelcontextprotocol/sdk zod
-   ```
-
-2. **Configure your MCP client**
-
-   **Cursor** (`.cursor/mcp.json`):
-   ```json
-   {
-     "mcpServers": {
-       "codebase-index": {
-         "command": "npx",
-         "args": ["opencode-codebase-index-mcp", "--project", "/path/to/your/project"]
-       }
-     }
-   }
-   ```
-
-   **Claude Code** (`claude_desktop_config.json`):
-   ```json
-   {
-     "mcpServers": {
-       "codebase-index": {
-         "command": "npx",
-         "args": ["opencode-codebase-index-mcp", "--project", "/path/to/your/project"]
-       }
-     }
-   }
-   ```
-
-3. **CLI options**
-   ```bash
-   npx opencode-codebase-index-mcp --project /path/to/repo    # specify project root
-   npx opencode-codebase-index-mcp --config /path/to/config   # custom config file
-   npx opencode-codebase-index-mcp                            # uses current directory
-   ```
-
-The MCP server exposes all 9 tools (`codebase_search`, `codebase_peek`, `find_similar`, `call_graph`, `index_codebase`, `index_status`, `index_health_check`, `index_metrics`, `index_logs`) and 4 prompts (`search`, `find`, `index`, `status`).
-
-The MCP dependencies (`@modelcontextprotocol/sdk`, `zod`) are optional peer dependencies — they're only needed if you use the MCP server.
-
-## 🔍 See It In Action
-
-**Scenario**: You're new to a codebase and need to fix a bug in the payment flow.
-
-**Without Plugin (grep)**:
-- `grep "payment" .` → 500 results (too many)
-- `grep "card" .` → 200 results (mostly UI)
-- `grep "stripe" .` → 50 results (maybe?)
-
-**With `opencode-codebase-index`**:
-You ask: *"Where is the payment validation logic?"*
-
-Plugin returns:
-```text
-src/services/billing.ts:45  (Class PaymentValidator)
-src/utils/stripe.ts:12      (Function validateCardToken)
-src/api/checkout.ts:89      (Route handler for /pay)
-```
-
-## 🎯 When to Use What
-
-| Scenario | Tool | Why |
-|----------|------|-----|
-| Don't know the function name | `codebase_search` | Semantic search finds by meaning |
-| Exploring unfamiliar codebase | `codebase_search` | Discovers related code across files |
-| Just need to find locations | `codebase_peek` | Returns metadata only, saves ~90% tokens |
-| Understand code flow | `call_graph` | Find callers/callees of any function |
-| Know exact identifier | `grep` | Faster, finds all occurrences |
-| Need ALL matches | `grep` | Semantic returns top N only |
-| Mixed discovery + precision | `/find` (hybrid) | Best of both worlds |
-
-**Rule of thumb**: `codebase_peek` to find locations → `Read` to examine → `grep` for precision.
-
-## 📊 Token Usage
-
-In our testing across open-source codebases (axios, express), we observed **up to 90% reduction in token usage** for conceptual queries like *"find the error handling middleware"*.
-
-### Why It Saves Tokens
-
-- **Without plugin**: Agent explores files, reads code, backtracks, explores more
-- **With plugin**: Semantic search returns relevant code immediately → less exploration
-
-### Key Takeaways
-
-1. **Significant savings possible**: Up to 90% reduction in the best cases
-2. **Results vary**: Savings depend on query type, codebase structure, and agent behavior
-3. **Best for discovery**: Conceptual queries benefit most; exact identifier lookups should use grep
-4. **Complements existing tools**: Provides a faster initial signal, doesn't replace grep/explore
-
-### When the Plugin Helps Most
-
-- **Conceptual queries**: "Where is the authentication logic?" (no keywords to grep for)
-- **Unfamiliar codebases**: You don't know what to search for yet
-- **Large codebases**: Semantic search scales better than exhaustive exploration
-
-## 🛠️ How It Works
-
-```mermaid
-graph TD
-    subgraph Indexing
-    A[Source Code] -->|Tree-sitter| B[Semantic Chunks]
-    B -->|Embedding Model| C[Vectors]
-    C -->|uSearch| D[(Vector Store)]
-    C -->|SQLite| G[(Embeddings DB)]
-    B -->|BM25| E[(Inverted Index)]
-    B -->|Branch Catalog| G
-    end
-
-    subgraph Searching
-    Q[User Query] -->|Embedding Model| V[Query Vector]
-    V -->|Cosine Similarity| D
-    Q -->|BM25| E
-    D --> F[Hybrid Fusion RRF/Weighted]
-    E --> F
-    F --> X[Deterministic Rerank]
-    G -->|Branch + Metadata Filters| X
-    X --> R[Ranked Results]
-    end
-```
-
-1. **Parsing**: We use `tree-sitter` to intelligently parse your code into meaningful blocks (functions, classes, interfaces). JSDoc comments and docstrings are automatically included with their associated code.
-
-**Supported Languages**: TypeScript, JavaScript, Python, Rust, Go, Java, C#, Ruby, Bash, C, C++, JSON, TOML, YAML
-2. **Chunking**: Large blocks are split with overlapping windows to preserve context across chunk boundaries.
-3. **Embedding**: These blocks are converted into vector representations using your configured AI provider.
-4. **Storage**: Embeddings are stored in SQLite (deduplicated by content hash) and vectors in `usearch` with F16 quantization for 50% memory savings. A branch catalog tracks which chunks exist on each branch.
-5. **Hybrid Search**: Combines semantic similarity (vectors) with BM25 keyword matching, fuses (`rrf` default, `weighted` fallback), applies deterministic rerank, then filters by current branch/metadata.
-
-**Performance characteristics:**
-- **Incremental indexing**: ~50ms check time — only re-embeds changed files
-- **Smart chunking**: Understands code structure to keep functions whole, with overlap for context
-- **Native speed**: Core logic written in Rust for maximum performance
-- **Memory efficient**: F16 vector quantization reduces index size by 50%
-- **Branch-aware**: Automatically tracks which chunks exist on each git branch
-- **Provider validation**: Detects embedding provider/model changes and requires rebuild to prevent garbage results
-
-## 🌿 Branch-Aware Indexing
+> Fork of [opencode-codebase-index](https://github.com/Helweg/opencode-codebase-index) by Kenneth Helweg
 
-The plugin automatically detects git branches and optimizes indexing across branch switches.
+Semantic codebase indexing and search — with a standalone **git-native CLI** for incremental indexing via git hooks and worktree-aware querying.
 
-### How It Works
+## What this fork adds
 
-When you switch branches, code changes but embeddings for unchanged content remain the same. The plugin:
+- **Standalone CLI** (`codebase-index`) — runs without an MCP host
+- **Git hook integration** — automatic background reindexing on commit, merge, checkout, and rewrite
+- **Blob SHA incremental indexing** — diffs via `git hash-object` instead of reading files, skips unchanged files instantly
+- **Worktree-aware scoping** — `git ls-files` scopes queries to the current worktree checkout
 
-1. **Stores embeddings by content hash**: Embeddings are deduplicated across branches
-2. **Tracks branch membership**: A lightweight catalog tracks which chunks exist on each branch
-3. **Filters search results**: Queries only return results relevant to the current branch
+The upstream MCP server, OpenCode plugin, and all original features are preserved.
 
-### Benefits
+## Quick Start
 
-| Scenario | Without Branch Awareness | With Branch Awareness |
-|----------|-------------------------|----------------------|
-| Switch to feature branch | Re-index everything | Instant — reuse existing embeddings |
-| Return to main | Re-index everything | Instant — catalog already exists |
-| Search on branch | May return stale results | Only returns current branch's code |
+### Install
 
-### Automatic Behavior
-
-- **Branch detection**: Automatically reads from `.git/HEAD`
-- **Re-indexing on switch**: Triggers when you switch branches (via file watcher)
-- **Legacy migration**: Automatically migrates old indexes on first run
-- **Garbage collection**: Health check removes orphaned embeddings and chunks
-
-### Storage Structure
-
-```
-.opencode/index/
-├── codebase.db           # SQLite: embeddings, chunks, branch catalog, symbols, call edges
-├── vectors.usearch       # Vector index (uSearch)
-├── inverted-index.json   # BM25 keyword index
-└── file-hashes.json      # File change detection
+```bash
+npm install @khivi/opencode-codebase-index
 ```
 
-## 🧰 Tools Available
-
-The plugin exposes these tools to the OpenCode agent:
-
-### `codebase_search`
-**The primary tool.** Searches code by describing behavior.
-- **Use for**: Discovery, understanding flows, finding logic when you don't know the names.
-- **Example**: `"find the middleware that sanitizes input"`
-- **Ranking path**: hybrid retrieval → fusion (`search.fusionStrategy`) → deterministic rerank (`search.rerankTopN`) → filters
-
-**Writing good queries:**
-
-| ✅ Good queries (describe behavior) | ❌ Bad queries (too vague) |
-|-------------------------------------|---------------------------|
-| "function that validates email format" | "email" |
-| "error handling for failed API calls" | "error" |
-| "middleware that checks authentication" | "auth middleware" |
-| "code that calculates shipping costs" | "shipping" |
-| "where user permissions are checked" | "permissions" |
-
-### `codebase_peek`
-**Token-efficient discovery.** Returns only metadata (file, line, name, type) without code content.
-- **Use for**: Finding WHERE code is before deciding what to read. Saves ~90% tokens vs `codebase_search`.
-- **Ranking path**: same hybrid ranking path as `codebase_search` (metadata-only output)
-- **Example output**:
-  ```
-  [1] function "validatePayment" at src/billing.ts:45-67 (score: 0.92)
-  [2] class "PaymentProcessor" at src/processor.ts:12-89 (score: 0.87)
-  
-  Use Read tool to examine specific files.
-  ```
-- **Workflow**: `codebase_peek` → find locations → `Read` specific files
-
-### `find_similar`
-Find code similar to a provided snippet.
-- **Use for**: Duplicate detection, refactor prep, pattern mining.
-- **Ranking path**: semantic retrieval only + deterministic rerank (no BM25, no RRF).
-
-### `index_codebase`
-Manually trigger indexing.
-- **Use for**: Forcing a re-index or checking stats.
-- **Parameters**: `force` (rebuild all), `estimateOnly` (check costs), `verbose` (show skipped files and parse failures).
-
-### `index_status`
-Checks if the index is ready and healthy.
-
-### `index_health_check`
-Maintenance tool to remove stale entries from deleted files and orphaned embeddings/chunks from the database.
-
-### `index_metrics`
-Returns collected metrics about indexing and search performance. Requires `debug.enabled` and `debug.metrics` to be `true`.
-- **Metrics include**: Files indexed, chunks created, cache hit rate, search timing breakdown, GC stats, embedding API call stats.
-
-### `index_logs`
-Returns recent debug logs with optional filtering.
-- **Parameters**: `category` (optional: `search`, `embedding`, `cache`, `gc`, `branch`), `level` (optional: `error`, `warn`, `info`, `debug`), `limit` (default: 50).
-
-### `call_graph`
-Query the call graph to find callers or callees of a function/method. Automatically built during indexing for TypeScript, JavaScript, Python, Go, and Rust.
-- **Use for**: Understanding code flow, tracing dependencies, impact analysis.
-- **Parameters**: `name` (function name), `direction` (`callers` or `callees`), `symbolId` (required for `callees`, returned by previous queries).
-- **Example**: Find who calls `validateToken` → `call_graph(name="validateToken", direction="callers")`
-
-## 🎮 Slash Commands
-
-The plugin automatically registers these slash commands:
+### Set up an embedding provider
 
-| Command | Description |
-| ------- | ----------- |
-| `/search <query>` | **Pure Semantic Search**. Best for "How does X work?" |
-| `/find <query>` | **Hybrid Search**. Combines semantic search + grep. Best for "Find usage of X". |
-| `/index` | **Update Index**. Forces a refresh of the codebase index. |
-| `/status` | **Check Status**. Shows if indexed, chunk count, and provider info. |
+You need one embedding provider. The easiest local option:
 
-## ⚙️ Configuration
-
-Zero-config by default (uses `auto` mode). Customize in `.opencode/codebase-index.json`:
-
-```json
-{
-  "embeddingProvider": "auto",
-  "scope": "project",
-  "indexing": {
-    "autoIndex": false,
-    "watchFiles": true,
-    "maxFileSize": 1048576,
-    "maxChunksPerFile": 100,
-    "semanticOnly": false,
-    "autoGc": true,
-    "gcIntervalDays": 7,
-    "gcOrphanThreshold": 100,
-    "requireProjectMarker": true
-  },
-  "search": {
-    "maxResults": 20,
-    "minScore": 0.1,
-    "hybridWeight": 0.5,
-    "fusionStrategy": "rrf",
-    "rrfK": 60,
-    "rerankTopN": 20,
-    "contextLines": 0
-  },
-  "debug": {
-    "enabled": false,
-    "logLevel": "info",
-    "metrics": false
-  }
-}
+```bash
+brew install ollama            # install Ollama
+ollama pull nomic-embed-text   # pull the embedding model (~274MB)
 ```
 
-### Options Reference
-
-| Option | Default | Description |
-|--------|---------|-------------|
-| `embeddingProvider` | `"auto"` | Which AI to use: `auto`, `github-copilot`, `openai`, `google`, `ollama`, `custom` |
-| `scope` | `"project"` | `project` = index per repo, `global` = shared index across repos |
-| **indexing** | | |
-| `autoIndex` | `false` | Automatically index on plugin load |
-| `watchFiles` | `true` | Re-index when files change |
-| `maxFileSize` | `1048576` | Skip files larger than this (bytes). Default: 1MB |
-| `maxChunksPerFile` | `100` | Maximum chunks to index per file (controls token costs for large files) |
-| `semanticOnly` | `false` | When `true`, only index semantic nodes (functions, classes) and skip generic blocks |
-| `retries` | `3` | Number of retry attempts for failed embedding API calls |
-| `retryDelayMs` | `1000` | Delay between retries in milliseconds |
-| `autoGc` | `true` | Automatically run garbage collection to remove orphaned embeddings/chunks |
-| `gcIntervalDays` | `7` | Run GC on initialization if last GC was more than N days ago |
-| `gcOrphanThreshold` | `100` | Run GC after indexing if orphan count exceeds this threshold |
-| `requireProjectMarker` | `true` | Require a project marker (`.git`, `package.json`, etc.) to enable file watching and auto-indexing. Prevents accidentally indexing large directories like home. Set to `false` to index any directory. |
-| **search** | | |
-| `maxResults` | `20` | Maximum results to return |
-| `minScore` | `0.1` | Minimum similarity score (0-1). Lower = more results |
-| `hybridWeight` | `0.5` | Balance between keyword (1.0) and semantic (0.0) search |
-| `fusionStrategy` | `"rrf"` | Hybrid fusion mode: `"rrf"` (rank-based reciprocal rank fusion) or `"weighted"` (legacy score blending fallback) |
-| `rrfK` | `60` | RRF smoothing constant. Higher values flatten rank impact, lower values prioritize top-ranked candidates more strongly |
-| `rerankTopN` | `20` | Deterministic rerank depth cap. Applies lightweight name/path/chunk-type rerank to top-N only |
-| `contextLines` | `0` | Extra lines to include before/after each match |
-| **debug** | | |
-| `enabled` | `false` | Enable debug logging and metrics collection |
-| `logLevel` | `"info"` | Log level: `error`, `warn`, `info`, `debug` |
-| `logSearch` | `true` | Log search operations with timing breakdown |
-| `logEmbedding` | `true` | Log embedding API calls (success, error, rate-limit) |
-| `logCache` | `true` | Log cache hits and misses |
-| `logGc` | `true` | Log garbage collection operations |
-| `logBranch` | `true` | Log branch detection and switches |
-| `metrics` | `false` | Enable metrics collection (indexing stats, search timing, cache performance) |
-
-### Retrieval ranking behavior (Phase 1)
-
-- `codebase_search` and `codebase_peek` use the hybrid path: semantic + keyword retrieval → fusion (`fusionStrategy`) → deterministic rerank (`rerankTopN`) → filtering.
-- `find_similar` stays semantic-only: semantic retrieval + deterministic rerank only (no keyword retrieval, no RRF).
-- For compatibility rollbacks, set `search.fusionStrategy` to `"weighted"` to use the legacy weighted fusion path.
-- Retrieval benchmark artifacts are separated by role:
-  - baseline (versioned): `benchmarks/baselines/retrieval-baseline.json`
-  - latest candidate run (generated): `benchmark-results/retrieval-candidate.json`
-
-### Embedding Providers
-The plugin automatically detects available credentials in this order:
-1. **GitHub Copilot** (Free if you have it)
-2. **OpenAI** (Standard Embeddings)
-3. **Google** (Gemini Embeddings)
-4. **Ollama** (Local/Private - requires `nomic-embed-text`)
-
-You can also use **Custom** to connect any OpenAI-compatible embedding endpoint (llama.cpp, vLLM, text-embeddings-inference, LiteLLM, etc.).
-
-### Rate Limits by Provider
-
-Each provider has different rate limits. The plugin automatically adjusts concurrency and delays:
-
-| Provider | Concurrency | Delay | Best For |
-|----------|-------------|-------|----------|
-| **GitHub Copilot** | 1 | 4s | Small codebases (<1k files) |
-| **OpenAI** | 3 | 500ms | Medium codebases |
-| **Google** | 5 | 200ms | Medium-large codebases |
-| **Ollama** | 5 | None | Large codebases (10k+ files) |
-| **Custom** | 3 | 1s | Any OpenAI-compatible endpoint |
-
-**For large codebases**, use Ollama locally to avoid rate limits:
+Or use a cloud provider:
 
 ```bash
-# Install the embedding model
-ollama pull nomic-embed-text
+export OPENAI_API_KEY=sk-...   # OpenAI
+# or
+export GOOGLE_API_KEY=...      # Google
+# or have an active GitHub Copilot subscription
 ```
 
-```json
-// .opencode/codebase-index.json
-{
-  "embeddingProvider": "ollama"
-}
-```
-
-## 📈 Performance
+The package auto-detects whichever is available.
 
-The plugin is built for speed with a Rust native module. Here are typical performance numbers (Apple M1):
+### Set up git hooks (one-time, per repo)
 
-### Parsing (tree-sitter)
-
-| Files | Chunks | Time |
-|-------|--------|------|
-| 100 | 1,200 | ~7ms |
-| 500 | 6,000 | ~32ms |
+```bash
+codebase-index install
+```
 
-### Vector Search (usearch)
+This installs hooks in `.git/hooks/` (worktree-aware via `--git-common-dir`):
+- `post-commit` — reindex after commits
+- `post-merge` — reindex after merges (symlink to post-commit)
+- `post-rewrite` — reindex after rebases (symlink to post-commit)
+- `post-checkout` — reindex on branch switch (with `[ "$3" = "1" ]` guard)
 
-| Index Size | Search Time | Throughput |
-|------------|-------------|------------|
-| 1,000 vectors | 0.7ms | 1,400 ops/sec |
-| 5,000 vectors | 1.2ms | 850 ops/sec |
-| 10,000 vectors | 1.3ms | 780 ops/sec |
+All hooks run `codebase-index incremental` in the background (`&`).
 
-### Database Operations (SQLite with batch)
+### Full index
 
-| Operation | 1,000 items | 10,000 items |
-|-----------|-------------|--------------|
-| Insert chunks | 4ms | 44ms |
-| Add to branch | 2ms | 22ms |
-| Check embedding exists | <0.01ms | <0.01ms |
+```bash
+codebase-index index
+```
 
-### Batch vs Sequential Performance
+### Incremental update (what the hooks run)
 
-Batch operations provide significant speedups:
+```bash
+codebase-index incremental
+```
 
-| Operation | Sequential | Batch | Speedup |
-|-----------|------------|-------|---------|
-| Insert 1,000 chunks | 38ms | 4ms | **~10x** |
-| Add 1,000 to branch | 29ms | 2ms | **~14x** |
-| Insert 1,000 embeddings | 59ms | 40ms | **~1.5x** |
+Compares blob SHAs of tracked files against stored hashes. Only triggers the indexer when files actually changed.
 
-Run benchmarks yourself: `npx tsx benchmarks/run.ts`
+### Query
 
-## 🎯 Choosing a Provider
+```bash
+codebase-index query "authentication middleware" --limit 5
+```
 
-Use this decision tree to pick the right embedding provider:
+Results are scoped to the current worktree's `git ls-files`:
 
 ```
-                    ┌─────────────────────────┐
-                    │ Do you have Copilot?    │
-                    └───────────┬─────────────┘
-                          ┌─────┴─────┐
-                         YES          NO
-                          │            │
-              ┌───────────▼───────┐    │
-              │ Codebase < 1k     │    │
-              │ files?            │    │
-              └─────────┬─────────┘    │
-                  ┌─────┴─────┐        │
-                 YES          NO       │
-                  │            │       │
-                  ▼            │       │
-           ┌──────────┐        │       │
-           │ Copilot  │        │       │
-           │ (free)   │        │       │
-           └──────────┘        │       │
-                               ▼       ▼
-                    ┌─────────────────────────┐
-                    │ Need fastest indexing?  │
-                    └───────────┬─────────────┘
-                          ┌─────┴─────┐
-                         YES          NO
-                          │            │
-                          ▼            ▼
-                   ┌──────────┐ ┌──────────────┐
-                   │ Ollama   │ │ OpenAI or    │
-                   │ (local)  │ │ Google       │
-                   └──────────┘ └──────────────┘
+src/auth/validator.ts:45  validateToken  0.923
+src/middleware/auth.ts:12  authMiddleware  0.891
+src/api/login.ts:89  handleLogin  0.847
 ```
 
-### Provider Comparison
+### Status
 
-| Provider | Speed | Cost | Privacy | Best For |
-|----------|-------|------|---------|----------|
-| **Ollama** | Fastest | Free | Full | Large codebases, privacy-sensitive |
-| **GitHub Copilot** | Slow (rate limited) | Free* | Cloud | Small codebases, existing subscribers |
-| **OpenAI** | Medium | ~$0.0001/1K tokens | Cloud | General use |
-| **Google** | Fast | Free tier available | Cloud | Medium-large codebases |
-| **Custom** | Varies | Varies | Varies | Self-hosted or third-party endpoints |
+```bash
+codebase-index status
+```
 
-*Requires active Copilot subscription
+## CLI Commands
 
-### Setup by Provider
+| Command | Description |
+|---------|-------------|
+| `codebase-index install` | Install git hooks for automatic incremental indexing |
+| `codebase-index index` | Full reindex of the codebase |
+| `codebase-index incremental` | Incremental update — only changed files (blob SHA diff) |
+| `codebase-index query <text>` | Worktree-scoped semantic search |
+| `codebase-index status` | Show index status |
 
-**Ollama (Recommended for large codebases)**
-```bash
-ollama pull nomic-embed-text
-```
-```json
-{ "embeddingProvider": "ollama" }
-```
+## MCP Server (Cursor, Claude Code, Windsurf)
 
-**OpenAI**
-```bash
-export OPENAI_API_KEY=sk-...
-```
-```json
-{ "embeddingProvider": "openai" }
-```
+The MCP server from upstream is fully preserved:
 
-**Google**
 ```bash
-export GOOGLE_API_KEY=...
-```
-```json
-{ "embeddingProvider": "google" }
+npm install @khivi/opencode-codebase-index @modelcontextprotocol/sdk zod
 ```
 
-**GitHub Copilot**
-No setup needed if you have an active Copilot subscription.
-```json
-{ "embeddingProvider": "github-copilot" }
-```
-
-**Custom (OpenAI-compatible)**
-Works with any server that implements the OpenAI `/v1/embeddings` API format (llama.cpp, vLLM, text-embeddings-inference, LiteLLM, etc.).
+**Cursor** (`.cursor/mcp.json`):
 ```json
 {
-  "embeddingProvider": "custom",
-  "customProvider": {
-    "baseUrl": "http://localhost:11434/v1",
-    "model": "nomic-embed-text",
-    "dimensions": 768,
-    "apiKey": "optional-api-key",
-    "maxTokens": 8192,
-    "timeoutMs": 30000
+  "mcpServers": {
+    "codebase-index": {
+      "command": "npx",
+      "args": ["opencode-codebase-index-mcp", "--project", "/path/to/your/project"]
+    }
   }
 }
 ```
-Required fields: `baseUrl`, `model`, `dimensions` (positive integer). Optional: `apiKey`, `maxTokens`, `timeoutMs` (default: 30000).
-
-## ⚠️ Tradeoffs
-
-Be aware of these characteristics:
-
-| Aspect | Reality |
-|--------|---------|
-| **Search latency** | ~800-1000ms per query (embedding API call) |
-| **First index** | Takes time depending on codebase size (e.g., ~30s for 500 chunks) |
-| **Requires API** | Needs an embedding provider (Copilot, OpenAI, Google, or local Ollama) |
-| **Token costs** | Uses embedding tokens (free with Copilot, minimal with others) |
-| **Best for** | Discovery and exploration, not exhaustive matching |
-
-## 💻 Local Development
 
-1. **Build**:
-   ```bash
-   npm run build
-   ```
+Exposes 9 tools: `codebase_search`, `codebase_peek`, `find_similar`, `call_graph`, `index_codebase`, `index_status`, `index_health_check`, `index_metrics`, `index_logs`.
 
-2. **Register in Test Project** (use `file://` URL in `opencode.json`):
-   ```json
-   {
-     "plugin": [
-       "file:///path/to/opencode-codebase-index"
-     ]
-   }
-   ```
-   
-   This loads directly from your source directory, so changes take effect after rebuilding.
+## Configuration
 
-## 🤝 Contributing
+Zero-config by default. Customize in `.opencode/codebase-index.json`:
 
-1. Fork the repository
-2. Create a feature branch: `git checkout -b feature/my-feature`
-3. Make your changes and add tests
-4. Run checks: `npm run build && npm run test:run && npm run lint`
-5. Commit: `git commit -m "feat: add my feature"`
-6. Push and open a pull request
+```json
+{
+  "embeddingProvider": "auto",
+  "scope": "project",
+  "indexing": {
+    "autoIndex": false,
+    "watchFiles": true,
+    "maxFileSize": 1048576,
+    "maxChunksPerFile": 100,
+    "semanticOnly": false
+  },
+  "search": {
+    "maxResults": 20,
+    "minScore": 0.1,
+    "hybridWeight": 0.5,
+    "fusionStrategy": "rrf"
+  }
+}
+```
 
-CI will automatically run tests and type checking on your PR.
+### Embedding Providers
 
-### Release process (structured + complete notes)
+Auto-detected in order: GitHub Copilot, OpenAI, Google, Ollama. Or set explicitly:
 
-To ensure release notes reflect all merged work, this repo uses a draft-release workflow.
+| Provider | Setup | Best For |
+|----------|-------|----------|
+| **GitHub Copilot** | Have active subscription | Small codebases (<1k files) |
+| **OpenAI** | `export OPENAI_API_KEY=sk-...` | General use |
+| **Google** | `export GOOGLE_API_KEY=...` | Medium-large codebases |
+| **Ollama** | `ollama pull nomic-embed-text` | Large codebases, privacy |
+| **Custom** | OpenAI-compatible endpoint | Self-hosted |
 
-1. **Label every PR** with at least one semantic label:
-   - `feature`, `bug`, `performance`, `documentation`, `dependencies`, `refactor`, `test`, `chore`
-   - and (when relevant) `semver:major`, `semver:minor`, or `semver:patch`
-   - PRs are validated by CI (`Release Label Check`) and fail if no release category label is present
-2. **Let Release Drafter build the draft notes** automatically from merged PRs on `main`.
-3. **Before publishing**:
-   - copy/finalize relevant highlights into `CHANGELOG.md`
-   - bump `package.json` version
-   - run: `npm run build && npm run typecheck && npm run lint && npm run test:run`
-4. **Publish release** from the draft (or via `gh release create` after reviewing draft content).
+## How It Works
 
-PRs labeled `skip-changelog` are intentionally excluded from release notes.
+1. **Parsing** — tree-sitter (Rust native) splits code into semantic chunks (functions, classes, interfaces)
+2. **Embedding** — chunks are vectorized via your configured AI provider
+3. **Storage** — vectors in usearch (F16 quantization), metadata in SQLite, keywords in BM25 inverted index
+4. **Search** — hybrid semantic + keyword retrieval, RRF fusion, deterministic reranking
+5. **Incremental** — blob SHAs track changes, only re-embeds what changed
 
-### Project Structure
+### Storage Structure
 
 ```
-├── src/
-│   ├── index.ts              # Plugin entry point
-│   ├── mcp-server.ts         # MCP server (Cursor, Claude Code, Windsurf)
-│   ├── cli.ts                # CLI entry for MCP stdio transport
-│   ├── config/               # Configuration schema
-│   ├── embeddings/           # Provider detection and API calls
-│   ├── indexer/              # Core indexing logic + inverted index
-│   ├── git/                  # Git utilities (branch detection)
-│   ├── tools/                # OpenCode tool definitions
-│   ├── utils/                # File collection, cost estimation
-│   ├── native/               # Rust native module wrapper
-│   └── watcher/              # File/git change watcher
-├── native/
-│   └── src/                  # Rust: tree-sitter, usearch, xxhash, SQLite
-├── tests/                    # Unit tests (vitest)
-├── commands/                 # Slash command definitions
-├── skill/                    # Agent skill guidance
-└── .github/workflows/        # CI/CD (test, build, publish)
+.opencode/index/
+├── codebase.db           # SQLite: embeddings, chunks, branch catalog, symbols, call edges
+├── vectors.usearch       # Vector index (uSearch)
+├── inverted-index.json   # BM25 keyword index
+└── file-hashes.json      # Blob SHA change detection
 ```
 
-### Native Module
-
-The Rust native module handles performance-critical operations:
-- **tree-sitter**: Language-aware code parsing with JSDoc/docstring extraction
-- **usearch**: High-performance vector similarity search with F16 quantization
-- **SQLite**: Persistent storage for embeddings, chunks, branch catalog, symbols, and call edges
-- **BM25 inverted index**: Fast keyword search for hybrid retrieval
-- **Call graph extraction**: Tree-sitter query-based extraction of function calls, method calls, constructors, and imports (TypeScript/JavaScript, Python, Go, Rust)
-- **xxhash**: Fast content hashing for change detection
-
-Rebuild with: `npm run build:native` (requires Rust toolchain)
-
-### Platform Support
+## Upstream Features
 
-Pre-built native binaries are published for:
+All upstream capabilities are preserved:
 
-| Platform | Architecture | SIMD Acceleration |
-|----------|-------------|--------------------|
-| macOS | x86_64 | ✅ simsimd |
-| macOS | ARM64 (Apple Silicon) | ✅ simsimd |
-| Linux | x86_64 (GNU) | ✅ simsimd |
-| Linux | ARM64 (GNU) | ✅ simsimd |
-| Windows | x86_64 (MSVC) | ❌ scalar fallback |
+- Branch-aware indexing with embedding reuse across branches
+- Call graph extraction (TypeScript, JavaScript, Python, Go, Rust)
+- Hybrid search (semantic + BM25 keyword)
+- OpenCode plugin with slash commands (`/search`, `/find`, `/index`, `/status`)
+- Native Rust module (tree-sitter, usearch, SQLite, xxhash)
+- Platform support: macOS (x86_64, ARM64), Linux (x86_64, ARM64), Windows (x86_64)
 
-Windows builds use scalar distance functions instead of SIMD — functionally identical, marginally slower for very large indexes. This is due to MSVC lacking support for certain AVX-512 intrinsics used by simsimd.
+For full upstream documentation, see the [original repository](https://github.com/Helweg/opencode-codebase-index).
 
 ## License
 
-MIT
+MIT — original work by [Kenneth Helweg](https://github.com/Helweg)