Development
Plugin
codebase-index
Search a codebase by meaning, then follow the result into definitions, callers, and dependency paths. open-codebase-index is a local semantic code index for OpenCode, Jcode, Pi, Codex, Claude Code, and other MCP clients.
Plugin Signal78/100Solid
maintained100
capable52
documented100
adopted47
Install on Claude Code
> /plugin marketplace add Helweg/open-codebase-index> /plugin install codebase-index@helweg-plugins
Stats
170
Stars
31
Forks
Active
Maintenance
TypeScript
Language
MIT
License
4h ago
Last commit
7mo ago
Created
Repo: Helweg/open-codebase-index
What's inside
Command(9 commands)
/call-graphTrace callers, callees, or paths using the call graph/definitionFind where a symbol is defined in the codebase/findFind code using hybrid approach (semantic + grep)/peekQuickly find likely code locations without returning full code/pr-impactAnalyze PR or branch impact using the call graph/reindexFully rebuild the codebase index from scratch
MCP(1 mcp)
Badges
README
open-codebase-index
Search a codebase by meaning, then follow the result into definitions, callers, and dependency paths.
open-codebase-index is a local semantic code index for OpenCode, Jcode, Pi, Codex, Claude Code, and other MCP clients. It combines embeddings, BM25 keyword search, branch-aware filtering, symbol lookup, and a call graph behind agent-friendly tools.
New installs should use open-codebase-index and open-codebase-index-mcp. The legacy package opencode-codebase-index and opencode-codebase-index-mcp remain supported aliases.
Highlights
- Semantic and hybrid retrieval for questions where you do not know the identifier.
- Low-token discovery through
codebase_contextandcodebase_peek. - Definition and graph navigation through
implementation_lookup,call_graph, andcall_graph_path. - Incremental, branch-aware indexing with file watching and content-hash reuse.
- Local storage backed by SQLite, usearch vectors, and a BM25 inverted index.
- Multiple embedding providers: Ollama, GitHub Copilot, OpenAI, Google, or a custom OpenAI-compatible endpoint.
- Native parsing for TypeScript/TSX, JavaScript/JSX, Python, Rust, Swift, Go, Java, C#, Ruby, C/C++, Metal, PHP, Apex, Bash, Zig, GDScript, MATLAB, JSON, TOML, YAML, Markdown, and HTML, with text fallback.
Quick start with OpenCode
Requires Node.js 20 or newer.
-
Install the package:
npm install open-codebase-indexLegacy installs continue to work with:
npm install opencode-codebase-index -
Add it to
opencode.json:{ "plugin": ["open-codebase-index"] }Legacy alias:
{ "plugin": ["opencode-codebase-index"] } -
Run
/status, then/index. -
Ask a repository question, for example:
Where is authentication state validated before an API request?
The first index creates embeddings. Later runs reuse unchanged content and process only relevant changes.
Choose your host
| Host | Recommended integration | Storage |
|---|---|---|
| OpenCode | Native plugin | .opencode/ |
| Jcode | Per-session MCP server | .codebase-index/ |
| Pi | Pi package | .codebase-index/ |
| Codex | Marketplace plugin with MCP and skill guidance | .codebase-index/ |
| Claude Code | Marketplace plugin with MCP and skill guidance | .claude/ |
| Cursor, Windsurf, other MCP clients | open-codebase-index-mcp (legacy alias: opencode-codebase-index-mcp) | Selected by --host; default is OpenCode-compatible |
See Installation and host setup for complete instructions.
Recommended workflow
- Check readiness with
index_statusor/status. - Index when needed with
index_codebaseor/index. - Start repository discovery with
codebase_context. - Use
codebase_peekwhen you only need likely locations. - Use
implementation_lookupfor a known symbol or definition question. - Use
codebase_searchwhen you need full matching source content. - Use
grepfor exact identifiers or exhaustive text matches. - Use call-graph tools for callers, callees, and dependency paths.
Which search tool should I use?
| Need | Tool |
|---|---|
| Route a repository question to a bounded evidence pack | codebase_context |
| Find likely files and symbols without source bodies | codebase_peek |
| Retrieve full matching code | codebase_search |
| Find an authoritative definition | implementation_lookup |
| Find analogous implementations or duplicates | find_similar |
| Find direct callers or callees | call_graph |
| Find a path between two symbols | call_graph_path |
| Analyze a branch or pull request blast radius | pr_impact |
See Tools and commands for host availability, tool details, MCP prompts, and slash commands.
How it works
source files
│
├─ file discovery and git-aware change detection
├─ tree-sitter parsing and semantic chunking
├─ embedding generation and content-hash reuse
▼
SQLite metadata + usearch vectors + BM25 index
│
├─ semantic candidates
├─ keyword candidates
├─ branch and request filters
├─ deterministic fusion and ranking
▼
locations, source results, definitions, and call-graph evidence
The TypeScript layer handles host integration, configuration, indexing orchestration, providers, ranking, and tools. The Rust NAPI module handles parsing, vector storage, SQLite operations, BM25 indexing, hashing, and call extraction.
Read Architecture for the detailed data flow and design decisions.
Embedding providers
With embeddingProvider: "auto", providers are tried in this order:
- Ollama
- GitHub Copilot
- OpenAI
Ollama is the simplest local option:
ollama pull nomic-embed-text
{
"embeddingProvider": "ollama"
}
A custom OpenAI-compatible embeddings endpoint is also supported. Provider, indexing, search, reranking, include/exclude, knowledge-base, storage, and debug settings are documented in Configuration.
Configuration example
OpenCode project config lives at .opencode/codebase-index.json. Codex, Pi, and Jcode use .codebase-index/config.json; Claude uses .claude/codebase-index.json.
{
"embeddingProvider": "auto",
"scope": "project",
"indexing": {
"autoIndex": false,
"watchFiles": true,
"requireProjectMarker": true,
"semanticOnly": false
},
"search": {
"maxResults": 20,
"minScore": 0.1,
"fusionStrategy": "rrf",
"rerankTopN": 20
}
}
Only specify values you want to override. See Configuration for defaults and host-specific paths.
Branch-aware indexing
The index stores reusable content by hash and maintains branch catalogs for chunks and symbols. On a branch switch, unchanged content can be reused while results remain scoped to the active branch. Linked worktrees without a local project config share the main checkout's portable project index; adding a worktree-local config creates an isolated index boundary.
Knowledge bases and reranking
OpenCode and Pi can index additional directories as knowledge bases. Configure them with knowledgeBases or use the host-native knowledge-base tools where available.
Optional external reranking supports Cohere, Jina, and custom compatible endpoints. Local filtering and evidence classes are applied before external candidates are submitted.
See Configuration for examples and privacy considerations.
Troubleshooting
Start with:
/statusorindex_statusindex_health_check- a normal
/indexretry - a forced rebuild only when status reports incompatibility or corruption
Common provider, native module, stale index, branch, and performance issues are covered in Troubleshooting.
Evaluation and performance
The repository includes reproducible retrieval datasets, latency and quality budgets, baseline comparison, and cross-repository benchmarking tools.
Performance depends on repository size, parser coverage, provider latency, embedding cache reuse, and the selected indexing limits. Prefer measured evaluation over fixed marketing claims.
Development
npm ci
npm run build
npm run typecheck
npm run lint
npm run test:run
Native changes require Rust and npm run build:native. See Contributing, Architecture, and Adding language support.
Documentation
- Installation and host setup
- Tools and commands
- Configuration
- Troubleshooting
- Architecture
- Evaluation
- Cross-repository benchmarking
- Adding language support
- Future
open-codebase-indexrename plan - Contributing
- Security
- Changelog
License
MIT. See LICENSE.
File tree
Helweg/open-codebase-indexView on GitHub
.agents/
plugins/
marketplace.json
.claude-plugin/
marketplace.json
plugin.json
.codex-plugin/
plugin.json
.github/
eval-config.json
eval-ollama-config.json
eval-ollama-full-config.json
ISSUE_TEMPLATE/
bug_report.md
feature_request.md
pull_request_template.md
release-drafter.yml
workflows/
build.yml
ci.yml
eval-quality.yml
release-drafter.yml
release-label-check.yml
.gitignore
.mcp.json
AGENTS.md
ARCHITECTURE.md
benchmarks/
baselines/
community-aware-ranking.json
eval-baseline-summary.json
intent-aware-ranking.json
privacy-safe-effectiveness.json
retrieval-baseline.json
budgets/
agent-context.json
default.json
ollama.json
pre-edit.json
representative.json
fixtures/
community-aware-ranking.json
indexing-memory-worker.ts
indexing-memory.json
intent-aware-ranking.json
privacy-safe-effectiveness.ts
golden/
agent-context.json
cross-repo/
axios.json
express.json
expanded-cross-repo/
axios.json
click.json
cobra.json
cohort.json
express.json
ripgrep.json
large.json
medium.json
pre-edit-context.json
representative.json
small.json
indexing-memory.ts
run.ts
CHANGELOG.md
CODE_OF_CONDUCT.md
commands/
call-graph.md
definition.md
find.md
index.md
peek.md
pr-impact.md
reindex.md
search.md
status.md
visualize.md
CONTRIBUTING.md
docs/
adding-language-support.md
benchmarking-cross-repo.md
benchmarks/
2026-08-09-expanded-cross-repo-definition-pilot.md
2026-08-09-expanded-cross-repo-mixed-intent-pilot.md
v0.22.0-vs-v0.21.0.md
codegraph-comparison-leadership-roadmap.md
configuration.md
evaluation.md
installation.md
pre-edit-context-design.md
public-benchmark-matrix.md
rename-to-open-codebase-index.md
tools.md
eslint.config.js
hooks/
hooks.json
LICENSE
native/
build.rs
Cargo.lock
Cargo.toml
package.json
queries/
apex-calls.scm
bash-calls.scm
c-calls.scm
cpp-calls.scm
gdscript-calls.scm
go-calls.scm
javascript-calls.scm
matlab-calls.scm
metal-calls.scm
php-calls.scm
python-calls.scm
rust-calls.scm
swift-calls.scm
typescript-calls.scm
zig-calls.scm
src/
bindings/
database.rs
mod.rs
call_extractor.rs
chunker.rs
community.rs
db/
db.rs
call_graph.rs
hasher.rs
inverted_index.rs
lib.rs
parser.rs
store.rs
types.rs
package-lock.json
package.json
README.md
scripts/
benchmark.sh
benchmark.ts
codegraph-baseline.ts
cross-repo-benchmark.ts
effectiveness-report.ts
eval-mock-embeddings-server.mjs
link-local-mcp-bin.mjs
prepare-package-metadata.mjs
run-build-native-with-rustflags.mjs
smoke-test-built-cli.mjs
smoke-test-packed-cli.mjs
SECURITY.md
skill/
SKILL.md
skills/
codebase-search/
SKILL.md
src/
adapters/
mcp/
cli.ts
register-prompts.ts
register-tools.ts
server.ts
shared.ts
opencode/
opencode.ts
pr-impact.ts
tools.ts
pi/
call-graph.ts
extension.ts
cli.ts
commands/
loader.ts
config/
constants.ts
defaults.ts
env-substitution.ts
host.ts
index.ts
merger.ts
paths.ts
rebase.ts
schema.ts
validators.ts
embeddings/
detector.ts
provider-types.ts
provider.ts
providers/
custom.ts
github-copilot.ts
google.ts
ollama.ts
openai.ts
eval/
budget.ts
cli-parser.ts
cli.ts
compare.ts
effectiveness-report.ts
metrics.ts
report-formatters.ts
reports.ts
runner-config.ts
runner.ts
schema.ts
types.ts
git/
branch-materialization.ts
branch-resolution.ts
index.ts
refs.ts
identity-catalog.json
identity-catalog.ts
index.ts
indexer/
call-graph-constants.ts
definition-ranking.ts
delta.ts
embedding-batches.ts
failed-state-persistence.ts
file-batches.ts
git-blame.ts
index-lock.ts
index.ts
intent-aware-ranking.ts
pr-impact-types.ts
search-ranking.ts
mcp-server.ts
native/
binding.ts
database.ts
embedding.ts
index.ts
inverted-index.ts
parsing.ts
types.ts
vector-store.ts
package-metadata.ts
pi-call-graph.ts
pi-extension.ts
routing-hints-patterns.ts
routing-hints.ts
tools/
changed-files.ts
config-state.ts
context-pack.ts
context-search.ts
context.ts
contracts.ts
edit-context.ts
execute-common.ts
format-communities.ts
format-pr-impact.ts
index.ts
knowledge-base-paths.ts
operation-runtime.ts
operations.ts
pr-impact.ts
symbol-inference.ts
tool-names.ts
utils.ts
visualize/
activity.ts
index.ts
modules.ts
template.ts
transform.ts
types.ts
utils/
auto-index.ts
canonical-path.ts
cost.ts
effectiveness-metrics.ts
files.ts
logger.ts
paths.ts
power-source.ts
url-validation.ts
watcher/
file-watcher.ts
git-head-watcher.ts
index.ts
tests/
auto-gc.test.ts
auto-index.test.ts
automatic-branch-index.test.ts
branch-materialization-multiprocess.test.ts
branch-materialization.test.ts
call-graph.test.ts
canonical-path.test.ts
changed-files.test.ts
claude-plugin.test.ts
cli.test.ts
codegraph-baseline.test.ts
codex-plugin.test.ts
commands.test.ts
communities.test.ts
community-ranking-eval.test.ts
community-ranking-integration.test.ts
community-ranking.test.ts
config-rebase.test.ts
config.test.ts
cost.test.ts
crash-recovery.test.ts
cross-repo-benchmark-dataset-dir.test.ts
cross-repo-codebase-memory.test.ts
cross-repo-codegraph.test.ts
custom-provider.test.ts
database.test.ts
definition-ranking.test.ts
edit-context.test.ts
effectiveness-ci.test.ts
effectiveness-metrics.test.ts
effectiveness-report.test.ts
effectiveness-watcher-lifetime.test.ts
embedding-batches.test.ts
embeddings.test.ts
eval-budget.test.ts
eval-cli.test.ts
eval-compare.test.ts
eval-metrics.test.ts
eval-reports.test.ts
eval-runner.test.ts
eval-schema.test.ts
file-batches.test.ts
files.test.ts
fixtures/
apex/
AccountServiceFixture.cls
bm25-publication-barrier.mjs
branch-materialization-oid-worker.ts
call-graph/
apex-constructors.cls
apex-method-calls.cls
apex-simple-calls.cls
c-calls.c
constructors.ts
cpp-calls.cpp
edge-cases.ts
imports.ts
method-calls.ts
nested-calls.ts
php-8-features.php
php-constructors.php
php-imports.php
php-method-calls.php
php-method-zeroalloc.php
php-simple-calls.php
same-file-refs.ts
simple-calls.ts
metal/
representative.metal
multiprocess-index-worker.ts
swift/
ModernService.swift
git-refs.test.ts
git.test.ts
host-mode-paths.test.ts
host-paths.test.ts
identity-phase0.test.ts
index-lock.test.ts
indexer-clear-index.test.ts
indexer-failed-batches.test.ts
indexer-failed-state-persistence.test.ts
indexer-file-batching.test.ts
indexing-transaction.test.ts
intent-aware-ranking-eval.test.ts
inverted-index.test.ts
logger.test.ts
mcp-cli-index.test.ts
mcp-lifecycle.test.ts
mcp-server.test.ts
multiprocess-indexing.test.ts
native.test.ts
paths.test.ts
pi-communities.test.ts
pi-conformance.test.ts
pi-package.test.ts
plugin-hooks.test.ts
power-source.test.ts
pr-impact.test.ts
retrieval-benchmark.test.ts
retrieval-ranking.test.ts
routing-hints.test.ts
search-integration.test.ts
startup-regression-harness.mjs
startup-regression.test.ts
symbol-inference.test.ts
tools-context.test.ts
tools-knowledge-bases.test.ts
tools-utils.test.ts
tsconfig.json
visualize.test.ts
watcher-config-refresh.test.ts
watcher-emfile.test.ts
watcher.test.ts
worktree-fallback.test.ts
THIRD_PARTY_LICENSES.md
... 4 moreFAQ
codebase-index is a Claude Code plugin with 1 hand-picked skill for development work, indexed on Flowy. Install it with the command on its page. It includes codebase-search. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.
- What is codebase-index?
- Search a codebase by meaning, then follow the result into definitions, callers, and dependency paths. open-codebase-index is a local semantic code index for OpenCode, Jcode, Pi, Codex, Claude Code, and other MCP clients.
- How do I install codebase-index?
- Run these in Claude Code: /plugin marketplace add Helweg/open-codebase-index then /plugin install codebase-index@helweg-plugins. Then prompt normally.
- Does codebase-index auto-invoke its skills?
- Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.
- Is codebase-index free?
- Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.