opencode-codebase-index 0.12.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,11 +8,14 @@
 
 > **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)
@@ -26,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)
@@ -38,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
@@ -62,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
 
@@ -402,6 +458,28 @@ Find the shortest known call-graph path between two symbols. Use it after `codeb
 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.
@@ -430,6 +508,7 @@ The plugin automatically registers these slash commands:
 | `/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. |
 
@@ -544,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

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.