opencode-codebase-index 0.3.0 → 0.4.0

package/README.md

@@ -64,11 +64,12 @@ src/api/checkout.ts:89      (Route handler for /pay)
 |----------|------|-----|
 | 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 |
 | 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**: Semantic search for discovery → grep for precision.
+**Rule of thumb**: `codebase_peek` to find locations → `Read` to examine → `grep` for precision.
 
 ## 📊 Token Usage
 
@@ -117,6 +118,8 @@ graph TD
 ```
 
 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.
@@ -185,6 +188,18 @@ The plugin exposes these tools to the OpenCode agent:
 | "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`.
+- **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
+
 ### `index_codebase`
 Manually trigger indexing.
 - **Use for**: Forcing a re-index or checking stats.
@@ -196,6 +211,14 @@ 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).
+
 ## 🎮 Slash Commands
 
 The plugin automatically registers these slash commands:
@@ -230,6 +253,11 @@ Zero-config by default (uses `auto` mode). Customize in `.opencode/codebase-inde
     "minScore": 0.1,
     "hybridWeight": 0.5,
     "contextLines": 0
+  },
+  "debug": {
+    "enabled": false,
+    "logLevel": "info",
+    "metrics": false
   }
 }
 ```
@@ -256,6 +284,15 @@ Zero-config by default (uses `auto` mode). Customize in `.opencode/codebase-inde
 | `minScore` | `0.1` | Minimum similarity score (0-1). Lower = more results |
 | `hybridWeight` | `0.5` | Balance between keyword (1.0) and semantic (0.0) search |
 | `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) |
 
 ### Embedding Providers
 The plugin automatically detects available credentials in this order: