Codebase Index

opencode-codebase-index

Stop grepping for concepts. Start searching for meaning.

opencode-codebase-index brings semantic understanding to your OpenCode, Pi, 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
• 🥧 Pi Package
• 🧩 Codex Plugin
• 🧩 Claude Code Plugin
• 🌐 MCP Server (Cursor, Claude Code, Windsurf, etc.)
• 🎯 When to Use What
• 🧭 OMO CodeGraph Compatibility
• 🧰 Tools Available
• 🎮 Slash Commands
• 📚 Knowledge Base
• 🔄 Reranking
• ⚙️ Configuration
• 🤝 Contributing

👋 Choose Your Path

• I want to try it now → go to Quick Start
• I use Pi → go to Pi Package
• I use Cursor/Claude Code/Windsurf → go to MCP Server setup
• I’m comparing tools and workflows → go to When to Use What
• I’m tuning behavior/cost/performance → go to Configuration
• I want to contribute → go to Contributing

🚀 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.
• 🥧 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

1. Install the plugin

   npm install opencode-codebase-index
   

2. Add to opencode.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.

   Recommended check: run /status after the first index so you can confirm the detected provider/model before you start searching.

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.

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

   codex plugin marketplace add Helweg/opencode-codebase-index
   

2. Install the plugin

   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

For local plugin development from this checkout, build and link the local MCP bin once:

npm run build:ts
npm run dev:link-mcp

After that, the normal .mcp.json command also works when Codex starts the plugin from this repository.