opencode-codebase-index 0.11.0 → 0.13.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "name": "helweg-plugins",
+  "owner": {
+    "name": "Kenneth",
+    "email": "kenneth@example.com",
+    "url": "https://github.com/Helweg/opencode-codebase-index"
+  },
+  "plugins": [
+    {
+      "name": "codebase-index",
+      "description": "Semantic code search and codebase graph tools for Claude Code",
+      "source": "./",
+      "version": "0.12.0"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,29 @@
+{
+  "name": "codebase-index",
+  "version": "0.13.0",
+  "description": "Semantic code search and codebase graph tools for Claude Code",
+  "displayName": "Codebase Index",
+  "author": {
+    "name": "Kenneth",
+    "email": "kenneth@example.com",
+    "url": "https://github.com/Helweg/opencode-codebase-index"
+  },
+  "homepage": "https://github.com/Helweg/opencode-codebase-index",
+  "repository": "https://github.com/Helweg/opencode-codebase-index",
+  "license": "MIT",
+  "keywords": [
+    "codebase-index",
+    "semantic search",
+    "claude",
+    "claude-code",
+    "mcp"
+  ],
+  "skills": "./skills/",
+  "hooks": "./hooks/hooks.json",
+  "mcpServers": {
+    "codebase-index": {
+      "command": "npx",
+      "args": ["-y", "--package", "opencode-codebase-index", "opencode-codebase-index-mcp", "--host", "claude"]
+    }
+  }
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,43 @@
+{
+  "name": "codebase-index",
+  "version": "0.13.0",
+  "description": "Semantic code search and codebase graph tools for Codex",
+  "author": {
+    "name": "Kenneth",
+    "email": "kenneth@example.com",
+    "url": "https://github.com/Helweg/opencode-codebase-index"
+  },
+  "homepage": "https://github.com/Helweg/opencode-codebase-index",
+  "repository": "https://github.com/Helweg/opencode-codebase-index",
+  "license": "MIT",
+  "keywords": [
+    "codebase-index",
+    "semantic search",
+    "opencode",
+    "codex",
+    "mcp"
+  ],
+  "skills": "./skills/",
+  "hooks": "./hooks/hooks.json",
+  "id": "codebase-index",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "Codebase Index",
+    "shortDescription": "Navigate large codebases with semantic search and graph tools",
+    "longDescription": "Install this plugin to get semantic search tools in Codex. The skill layer gives usage guidance, and MCP tools provide searchable context for large repos.",
+    "developerName": "Kenneth",
+    "category": "Productivity",
+    "capabilities": [
+      "Instructions",
+      "MCP Tools",
+      "Search"
+    ],
+    "websiteURL": "https://github.com/Helweg/opencode-codebase-index",
+    "privacyPolicyURL": "https://github.com/Helweg/opencode-codebase-index/blob/main/SECURITY.md",
+    "termsOfServiceURL": "https://github.com/Helweg/opencode-codebase-index/blob/main/LICENSE",
+    "brandColor": "#3B82F6",
+    "defaultPrompt": [
+      "Use codebase-search skills and MCP tools to find local implementation context before edits."
+    ]
+  }
+}

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "codebase-index": {
+      "command": "npx",
+      "args": ["-y", "--package", "opencode-codebase-index", "opencode-codebase-index-mcp", "--host", "codex"]
+    }
+  }
+}

package/README.md

@@ -8,13 +8,17 @@
 
 > **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.
+**opencode-codebase-index** brings semantic understanding to your [OpenCode](https://opencode.ai), [Pi](https://pi.dev), Codex, and MCP-compatible workflows. Instead of guessing function names or grepping for keywords, ask your codebase questions in plain English.
 
 ## 📌 Quick Navigation
 
 - [⚡ Quick Start](#-quick-start)
+- [🥧 Pi Package](#-pi-package)
+- [🧩 Codex Plugin](#-codex-plugin)
+- [🧩 Claude Code Plugin](#-claude-code-plugin)
 - [🌐 MCP Server (Cursor, Claude Code, Windsurf, etc.)](#-mcp-server-cursor-claude-code-windsurf-etc)
 - [🎯 When to Use What](#-when-to-use-what)
+- [🧭 OMO CodeGraph Compatibility](#-omo-codegraph-compatibility)
 - [🧰 Tools Available](#-tools-available)
 - [🎮 Slash Commands](#-slash-commands)
 - [📚 Knowledge Base](#-knowledge-base)
@@ -25,6 +29,7 @@
 ## 👋 Choose Your Path
 
 - **I want to try it now** → go to [Quick Start](#-quick-start)
+- **I use Pi** → go to [Pi Package](#-pi-package)
 - **I use Cursor/Claude Code/Windsurf** → go to [MCP Server setup](#-mcp-server-cursor-claude-code-windsurf-etc)
 - **I’m comparing tools and workflows** → go to [When to Use What](#-when-to-use-what)
 - **I’m tuning behavior/cost/performance** → go to [Configuration](#️-configuration)
@@ -37,6 +42,7 @@
 - 🌿 **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.
+- 🥧 **Pi Package**: First-class Pi extension and skill package with native tools.
 - 🌐 **MCP Server**: Use with Cursor, Claude Code, Windsurf, or any MCP-compatible client — index once, search from anywhere.
 
 ## ⚡ Quick Start
@@ -61,6 +67,57 @@
 4. **Start Searching**
    Ask:
    > "Find the function that handles credit card validation errors"
+## 🥧 Pi Package
+
+Install as a Pi package to get first-class `codebase_search`, `index_codebase`, call graph, PR impact, and knowledge-base tools plus the `codebase-search` skill.
+
+```bash
+pi install npm:opencode-codebase-index
+# or, for local development:
+pi install ./path/to/opencode-codebase-index
+```
+
+Pi uses the neutral `.codebase-index/` project storage and falls back to existing OpenCode state when present.
+
+## 🧩 Codex Plugin
+Install once for Codex threads and get skill guidance plus MCP tools in one manifest.
+
+1. **Add this repo as a marketplace source**
+   ```bash
+   codex plugin marketplace add Helweg/opencode-codebase-index
+   ```
+2. **Install the plugin**
+   ```bash
+   codex plugin add codebase-index@helweg-plugins
+   ```
+3. **Restart or open a new thread** in the target workspace.
+4. Use MCP tools (`index_codebase`, `index_status`, `codebase_search`, etc.) and the `codebase-search` skill guidance.
+
+The plugin includes:
+- `skills/` guidance for local workflows
+- `hooks/hooks.json` lightweight session-start guidance
+- `.mcp.json` running the published `opencode-codebase-index` CLI via `npx … --host codex`, so a git marketplace install works without a local build
+- `.agents/plugins/marketplace.json` so this repo can act as a Codex marketplace source
+
+## 🧩 Claude Code Plugin
+Install once for Claude Code sessions and get skill guidance plus MCP tools in one manifest.
+
+1. **Add this repo as a marketplace source**
+   ```bash
+   /plugin marketplace add Helweg/opencode-codebase-index
+   ```
+2. **Install the plugin**
+   ```bash
+   /plugin install codebase-index@helweg-plugins
+   ```
+3. **Restart or open a new session** in the target workspace.
+4. Use MCP tools (`index_codebase`, `index_status`, `codebase_search`, etc.) and the `codebase-search` skill guidance.
+
+The plugin includes:
+- `skills/` guidance for local workflows
+- `hooks/hooks.json` lightweight session-start guidance
+- inline `mcpServers` (in `.claude-plugin/plugin.json`) running the published `opencode-codebase-index` CLI via `npx … --host claude`, so a git marketplace install works without a local build
+- `.claude-plugin/marketplace.json` so this repo can act as a Claude Code marketplace source
 
 ### Provider selection notes
 
@@ -124,7 +181,7 @@ Use the same semantic search from any MCP-compatible client. Index once, search
    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 server exposes all 12 tools (`codebase_search`, `codebase_peek`, `find_similar`, `implementation_lookup`, `call_graph`, `call_graph_path`, `pr_impact`, `index_codebase`, `index_status`, `index_health_check`, `index_metrics`, `index_logs`) and 5 prompts (`search`, `find`, `definition`, `index`, `status`).
 
 The MCP dependencies (`@modelcontextprotocol/sdk`, `zod`) are optional peer dependencies — they're only needed if you use the MCP server.
 
@@ -156,12 +213,35 @@ src/api/checkout.ts:89      (Route handler for /pay)
 | Just need to find locations | `codebase_peek` | Returns metadata only, saves ~90% tokens |
 | Need the authoritative definition site | `implementation_lookup` | Prioritizes real implementation definitions over docs/tests |
 | Understand code flow | `call_graph` | Find callers/callees of any function |
+| Trace dependency paths | `call_graph_path` | Find the shortest known call path between two symbols |
 | 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. For symbol-definition questions, use `implementation_lookup` first.
 
+## 🧭 OMO CodeGraph Compatibility
+
+Recent OMO releases include a built-in CodeGraph MCP and make it part of the default agent workflow. This does **not** replace `opencode-codebase-index`; the two tools answer different first questions.
+
+| Need | Prefer | Why |
+|------|--------|-----|
+| Find code by intent, behavior, or natural language | `codebase_peek` / `codebase_search` | Semantic + hybrid retrieval works when you do not know exact names |
+| Jump to the likely implementation site | `implementation_lookup` | Definition-oriented ranking prefers source over tests/docs |
+| Find similar implementations or duplicate patterns | `find_similar` | Embedding similarity compares code shape and meaning |
+| Follow callers, callees, imports, inheritance, or implementations | OMO CodeGraph or `call_graph` | Structural graph tools are best for dependency topology |
+| Find a shortest known relationship chain | `call_graph_path` | Uses this plugin's indexed call edges to connect two symbols |
+| Include external docs, examples, or API references in discovery | `add_knowledge_base` + `codebase_search` | Knowledge bases are indexed into the same retrieval store |
+
+Recommended OMO workflow:
+
+1. Start broad with `codebase_peek` when the prompt is conceptual, such as "where is auth enforced?" or "payment validation flow".
+2. Use `implementation_lookup` once you have a symbol or concept that should resolve to a definition.
+3. Use OMO CodeGraph, `call_graph`, or `call_graph_path` after locating the relevant symbol to check blast radius and dependency flow.
+4. Keep `grep` for exact identifiers and exhaustive text matches.
+
+If OMO reports an uninitialized CodeGraph workspace, follow its `codegraph init` guidance. That setup is independent from this plugin's index under `.opencode/index/`, so `/index` and `codegraph init` may both be useful in the same repository.
+
 ## 📊 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"*.
@@ -363,9 +443,43 @@ Returns recent debug logs with optional filtering.
 Query the call graph to find callers or callees of a function/method. Automatically built during indexing for TypeScript, JavaScript, Python, Go, Rust, PHP, Apex, Zig, GDScript, and MATLAB.
 
 - **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).
+- **Parameters**: `name` (function name), `direction` (`callers` or `callees`), `symbolId` (required for `callees`, returned by previous queries), `relationshipType` (optional: `Call`, `MethodCall`, `Constructor`, `Import`, `Inherits`, `Implements`).
 - **Example**: Find who calls `validateToken` → `call_graph(name="validateToken", direction="callers")`
 
+### `call_graph_path`
+
+Find the shortest known call-graph path between two symbols. Use it after `codebase_peek`, `implementation_lookup`, or `call_graph` identifies the important source and target names.
+
+- **Use for**: Blast-radius checks, dependency-chain discovery, explaining how one subsystem reaches another.
+- **Parameters**: `from` (source symbol name), `to` (target symbol name), `maxDepth` (optional, default `10`).
+- **Example**: Trace how `createOrder` reaches `chargeCard` → `call_graph_path(from="createOrder", to="chargeCard")`
+
+### `pr_impact`
+Analyzes a PR's changed files to determine impact scope within the codebase.
+- **Use for**: Understanding which symbols are affected by a PR, their call-graph reach, risk level, and community/cluster detection.
+- **Parameters**: `checkConflicts` (optional, default `false`) — when `true`, detects overlapping concurrent PRs sharing affected symbols and returns `conflictingPRs`.
+
+### `index_visualize`
+Generate a self-contained temporal call graph view for browser-based exploration.
+
+- **Use for**: Onboarding, architecture walkthroughs, and understanding what moved recently before drilling into call relationships.
+- **What it shows**: Recent change lenses, module overview, symbol exploration, hotspots, and cycles.
+- **Concepts**: Modules are path-based code areas such as `src/tools` or `native`; symbols are indexed functions, classes, methods, or similar named code units; edges are caller/callee relationships.
+- **Parameters**: `directory` (optional folder filter), `maxNodes` (default `5000`), `includeOrphans` (include disconnected symbols).
+- **Output**: Writes a temporary HTML file you can open in any browser.
+- **Example**: `index_visualize(directory="src/tools", maxNodes=1500)`
+
+CLI shortcut after building locally:
+
+```bash
+npm run build
+npm run visualize
+npm run visualize -- native
+npm run visualize -- src/tools max=1000
+npm run visualize -- src/indexer orphans
+```
+
+
 ### `add_knowledge_base`
 Add a folder as a knowledge base to be indexed alongside project code.
 - **Use for**: Indexing external documentation, API references, example programs.
@@ -393,6 +507,8 @@ The plugin automatically registers these slash commands:
 | `/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". |
 | `/call-graph <query>` | **Call Graph Trace**. Find callers/callees to understand execution flow. |
+| `/pr-impact <PR number or branch>` | **PR Impact Analysis**. Analyze changed files, affected symbols, communities, hub nodes, and risk. |
+| `/visualize [directory|max=N|orphans]` | **Temporal Call Graph Visualization**. Open recent changes, module overview, symbol exploration, hotspots, and cycles in a browser-ready HTML file. |
 | `/index` | **Update Index**. Runs incremental indexing by default; use `/index force` for a full rebuild. |
 | `/status` | **Check Status**. Shows if indexed, chunk count, and provider info. |
 
@@ -507,6 +623,27 @@ Any OpenAI-compatible reranking endpoint. Examples:
 
 ## ⚙️ Configuration
 
+### Storage Paths (OpenCode + Codex + Claude + Pi)
+OpenCode default (existing behavior):
+- project config: `.opencode/codebase-index.json`
+- project index: `.opencode/index`
+- global config: `~/.config/opencode/codebase-index.json`
+- global index: `~/.opencode/global-index`
+
+Codex/Pi host mode (neutral default):
+- project config: `.codebase-index/config.json`
+- project index: `.codebase-index/index`
+- global config: `~/.config/codebase-index/config.json`
+- global index: `~/.codebase-index/global-index`
+
+Claude Code host mode (`--host claude`):
+- project config: `.claude/codebase-index.json`
+- project index: `.claude/index`
+- global config: `~/.claude/codebase-index.json`
+- global index: `~/.claude/global-index`
+
+Codex, Claude Code, and Pi read legacy OpenCode paths when host-native paths are absent, so existing state continues to work.
+
 Zero-config by default (uses `auto` mode). Customize in `.opencode/codebase-index.json`:
 
 ### Full Configuration Example
@@ -576,6 +713,7 @@ Zero-config by default (uses `auto` mode). Customize in `.opencode/codebase-inde
     "rerankTopN": 20,                         // Deterministic rerank depth
     "contextLines": 0,                        // Extra lines before/after match
     "routingHints": true,                     // Runtime nudges for local discovery/definition queries
+    "routingGraphHandoffHints": false,        // Add opt-in graph/OMO CodeGraph handoff wording
     "routingHintRole": "system"              // system | developer (message role used for hints)
   },
   "reranker": {
@@ -647,6 +785,7 @@ String values in `codebase-index.json` can reference environment variables with
 | `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 |
 | `routingHints` | `true` | Inject lightweight runtime hints for local conceptual discovery and definition lookups. Set to `false` to disable plugin-side routing nudges. |
+| `routingGraphHandoffHints` | `false` | When `true`, conceptual discovery hints also say to use graph tools (including OMO CodeGraph) after semantic discovery identifies relevant symbols. |
 | `routingHintRole` | `"system"` | Message role used when injecting routing hints: `"system"` (default) or `"developer"`. |
 | **reranker** | | Optional second-stage model reranker for the top candidate pool |
 | `enabled` | `false` | Turn external reranking on/off |
@@ -678,7 +817,7 @@ These warnings improve observability but do **not** change the recovery behavior
 ### Retrieval ranking behavior
 
 - `codebase_search` and `codebase_peek` use the hybrid path: semantic + keyword retrieval → fusion (`fusionStrategy`) → deterministic rerank (`rerankTopN`) → optional external reranker (`reranker`) → filtering.
-- When `search.routingHints` is enabled (default), the plugin adds tiny per-turn runtime hints for local conceptual discovery and definition queries. Conceptual discovery is nudged toward `codebase_peek` / `codebase_search`, while definition questions are nudged toward `implementation_lookup`. Exact identifier and unrelated operational tasks are left alone. Set `search.routingHintRole` to `"developer"` if your client/runtime expects developer-role guidance instead of system-role guidance.
+- When `search.routingHints` is enabled (default), the plugin adds tiny per-turn runtime hints for local conceptual discovery and definition queries. Conceptual discovery is nudged toward `codebase_peek` / `codebase_search`, while definition questions are nudged toward `implementation_lookup`. Exact identifier and unrelated operational tasks are left alone. Set `search.routingGraphHandoffHints` to `true` to add opt-in graph/OMO CodeGraph handoff wording, and set `search.routingHintRole` to `"developer"` if your client/runtime expects developer-role guidance instead of system-role guidance.
 - `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.
 - When enabled, the external reranker sees path metadata plus a bounded on-disk code snippet for each candidate so it can distinguish real implementations from docs/tests more reliably.

package/commands/call-graph.md

@@ -1,24 +1,28 @@
 ---
-description: Trace callers or callees using the call graph
+description: Trace callers, callees, or paths using the call graph
 ---
 
-Trace function dependencies using the `call_graph` tool.
+Trace function dependencies using the `call_graph` and `call_graph_path` tools.
 
 User input: $ARGUMENTS
 
 Interpret input as follows:
+- If input asks for a path, connection, route, chain, or "from X to Y", use `call_graph_path`.
 - Default to `direction="callers"` unless input asks for callees/calls/makes calls.
 - `name=<function>` or plain text function name sets `name`.
 - `symbolId=<id>` is required for `direction="callees"`.
+- For path queries, parse `from=<function>`, `to=<function>`, and optional `maxDepth=<number>`.
 
 Execution flow:
-1. If direction is `callers`, call `call_graph` with `{ name, direction: "callers" }`.
-2. If direction is `callees` and `symbolId` is present, call `call_graph` with `{ name, direction: "callees", symbolId }`.
-3. If direction is `callees` and `symbolId` is missing, first call `call_graph` with `direction="callers"` to get symbol IDs, then ask the user to choose one if multiple are returned.
+1. If input asks for a path and has source/target names, call `call_graph_path` with `{ from, to, maxDepth? }`.
+2. If direction is `callers`, call `call_graph` with `{ name, direction: "callers" }`.
+3. If direction is `callees` and `symbolId` is present, call `call_graph` with `{ name, direction: "callees", symbolId }`.
+4. If direction is `callees` and `symbolId` is missing, first call `call_graph` with `direction="callers"` to get symbol IDs, then ask the user to choose one if multiple are returned.
 
 Examples:
 - `/call-graph Database` → callers for `Database`
 - `/call-graph callers name=Indexer` → callers for `Indexer`
 - `/call-graph callees name=Database symbolId=sym_abc123` → callees for selected symbol
+- `/call-graph path from=createOrder to=chargeCard` → shortest known path between the two symbols
 
 If output says no callers found, suggest running `/index force` first.

package/commands/pr-impact.md

@@ -0,0 +1,23 @@
+---
+description: Analyze PR or branch impact using the call graph
+---
+
+Analyze the impact of a pull request or branch before merging.
+
+User input: $ARGUMENTS
+
+Interpret input as follows:
+- `pr=N` or plain number at the start → set `pr`
+- `branch=<name>` or plain branch name → set `branch`
+- `maxDepth=N` → set max traversal depth
+- `hubThreshold=N` → set hub node threshold
+- `checkConflicts` or `conflicts` → set `checkConflicts=true`
+
+Call `pr_impact` with the parsed arguments.
+
+Examples:
+- `/pr-impact 42` → pr=42
+- `/pr-impact branch=feature/auth` → branch="feature/auth"
+- `/pr-impact branch=feature/x maxDepth=3 checkConflicts` → branch="feature/x", maxDepth=3, checkConflicts=true
+
+If the index doesn't exist, run `index_codebase` first.

package/commands/visualize.md

@@ -0,0 +1,30 @@
+---
+description: Generate temporal HTML call graph visualization
+---
+
+Generate an interactive temporal call graph visualization that starts with recent movement/onboarding context, then supports module overview, symbol exploration, hotspots, and cycles.
+
+User input: $ARGUMENTS
+
+Parse input for optional parameters:
+- Plain text → directory filter (e.g., `/visualize src/services`)
+- `max=N` or "limit N" → sets maxNodes
+- `orphans` or `include-orphans` → sets includeOrphans=true
+- No input → visualize recent code movement plus entire call graph
+
+Call `index_visualize` with parsed parameters.
+
+Examples:
+- `/visualize` → temporal onboarding view with changes, modules, symbols, hotspots, and cycles
+- `/visualize src/tools` → only symbols in src/tools/
+- `/visualize max=1000` → limit to 1000 nodes
+- `/visualize src/indexer orphans` → include disconnected nodes
+
+If the index doesn't exist, run `index_codebase` first.
+
+Return the generated file path and open instructions.
+
+Terminology:
+- Modules are path-based code areas, such as `src/tools` or `native`.
+- Symbols are indexed named code units, such as functions, methods, classes, or Rust modules.
+- Cycles are loops where code can eventually call or depend back on itself.