Skip to content
Back to search

helweg-plugins

SkillGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Helweg/open-codebase-index with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Helweg/open-codebase-index'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/helweg--open-codebase-index/badge.svg)](/listings/helweg--open-codebase-index)

HTML

<a href="/listings/helweg--open-codebase-index"><img src="/api/listings/helweg--open-codebase-index/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires Node.js 22.22 or newer. Node.js 24 LTS is recommended.

1. Install the package:

   npm install open-codebase-index

Legacy installs continue to work with:

   npm install opencode-codebase-index

2. Add it to `opencode.json`:

For OpenCode 2.x:

   {
     "plugins": ["open-codebase-index"]
   }

For OpenCode 1.x (1.3.4 or newer):

   {
     "plugin": ["open-codebase-index"]
   }

Legacy alias (OpenCode 2.x):

   {
     "plugins": ["opencode-codebase-index"]
   }

Legacy alias (OpenCode 1.x):

   {
     "plugin": ["opencode-codebase-index"]
   }

3. Run `/status`, then `/index`. 4. 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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 16 lines
  1. {
  2. "name": "helweg-plugins",
  3. "owner": {
  4. "name": "Kenneth",
  5. "email": "kenneth@example.com",
  6. "url": "https://github.com/Helweg/open-codebase-index"
  7. },
  8. "plugins": [
  9. {
  10. "name": "codebase-index",
  11. "description": "Semantic code search and codebase graph tools for Claude Code",
  12. "source": "./",
  13. "version": "0.40.0"
  14. }
  15. ]
  16. }
README.md · README · 316 lines
  1. # open-codebase-index
  2. [![npm version](https://img.shields.io/npm/v/open-codebase-index.svg)](https://www.npmjs.com/package/open-codebase-index)
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  4. [![Downloads](https://img.shields.io/npm/dm/open-codebase-index.svg)](https://www.npmjs.com/package/open-codebase-index)
  5. [![Build Status](https://img.shields.io/github/actions/workflow/status/Helweg/open-codebase-index/ci.yml?branch=main)](https://github.com/Helweg/open-codebase-index/actions)
  6. [![Node.js](https://img.shields.io/badge/node-%3E%3D22.22-brightgreen.svg)](https://nodejs.org/)
  7. > Search a codebase by meaning, then follow the result into definitions, callers, and dependency paths.
  8. `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.
  9. 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.
  10. For terminal use outside an MCP client, install the package globally and use the concise `ocbi` command:
  11. ```bash
  12. npm install -g open-codebase-index
  13. ocbi status --project /path/to/repo --host jcode
  14. ocbi search "retry recovery" --project /path/to/repo
  15. ```
  16. `cbi` remains available as a compatibility alias. `ocbi` provides status, indexing, search, definition lookup, direct caller/callee inspection, and current indexed working-tree impact. See [Installation and host setup](docs/installation.md#human-cli) for the full command reference.
  17. ## Highlights
  18. - **Semantic and hybrid retrieval** for questions where you do not know the identifier.
  19. - **Low-token discovery** through `codebase_context` and `codebase_peek`.
  20. - **Definition and graph navigation** through `implementation_lookup`, `call_graph`, and `call_graph_path`.
  21. - **Incremental, branch-aware indexing** with file watching and content-hash reuse.
  22. - **Local storage** backed by SQLite, usearch vectors, and a BM25 inverted index.
  23. - **Multiple embedding providers**: Ollama, OpenAI, Google, or a custom OpenAI-compatible endpoint.
  24. - **Native parsing** for TypeScript/TSX, JavaScript/JSX, Python, Rust, Swift, Go, Kotlin (`.kt` and `.kts`), Java, C#, Ruby, C/C++, Metal, PHP, Apex, Bash, Zig, GDScript, MATLAB, JSON, TOML, YAML, Markdown, HTML, XML, and SVG, plus text fallback for other formats.
  25. ## Quick start with OpenCode
  26. Requires Node.js 22.22 or newer. Node.js 24 LTS is recommended.
  27. 1. Install the package:
  28. ```bash
  29. npm install open-codebase-index
  30. ```
  31. Legacy installs continue to work with:
  32. ```bash
  33. npm install opencode-codebase-index
  34. ```
  35. 2. Add it to `opencode.json`:
  36. For OpenCode 2.x:
  37. ```json
  38. {
  39. "plugins": ["open-codebase-index"]
  40. }
  41. ```
  42. For OpenCode 1.x (1.3.4 or newer):
  43. ```json
  44. {
  45. "plugin": ["open-codebase-index"]
  46. }
  47. ```
  48. Legacy alias (OpenCode 2.x):
  49. ```json
  50. {
  51. "plugins": ["opencode-codebase-index"]
  52. }
  53. ```
  54. Legacy alias (OpenCode 1.x):
  55. ```json
  56. {
  57. "plugin": ["opencode-codebase-index"]
  58. }
  59. ```
  60. 3. Run `/status`, then `/index`.
  61. 4. Ask a repository question, for example:
  62. > Where is authentication state validated before an API request?
  63. The first index creates embeddings. Later runs reuse unchanged content and process only relevant changes.
  64. ## Choose your host
  65. | Host | Recommended integration | Storage |
  66. |---|---|---|
  67. | OpenCode | Native plugin | `.opencode/` |
  68. | Jcode | Per-session MCP server | `.codebase-index/` |
  69. | Pi | Pi package | `.codebase-index/` |
  70. | omp (oh-my-pi) | omp package; CLI `--host omp` aliases `pi` | `.codebase-index/` (same as Pi) |
  71. | Codex | Marketplace plugin with MCP and skill guidance | `.codebase-index/` |
  72. | Claude Code | Marketplace plugin with MCP and skill guidance | `.claude/` |
  73. | Cursor, Windsurf, other MCP clients | `open-codebase-index-mcp` (legacy alias: `opencode-codebase-index-mcp`) | Selected by `--host`; default is OpenCode-compatible |
  74. See [Installation and host setup](docs/installation.md) for complete instructions.
  75. ## Recommended workflow
  76. 1. **Check stored readiness when unknown** with `index_status` or `/status`; use `index_status({checkFreshness:true})` when source/HEAD freshness matters. Ordinary status does not scan source; index only when needed.
  77. 2. **Orient in unfamiliar code** with one compact `codebase_context` first pass (`tokenBudget: 600`, `limit: 5`), then inspect the evidence. Skip this step when the task is already scoped.
  78. 3. **Go directly to known definitions or relationships** with `implementation_lookup`, `call_graph`, or `call_graph_path`.
  79. 4. **Optionally prepare a known edit target** with `codebase_edit_context` for bounded source and direct graph evidence; `includeTests:true` adds source-linked JS/TS test references, not runtime coverage.
  80. 5. **Choose metadata or matching source** with `codebase_peek` or `codebase_search`; do not repeat context calls unnecessarily.
  81. 6. **Read known paths or match literals directly** with targeted reads or `grep`.
  82. ### Which search tool should I use?
  83. | Need | Tool |
  84. |---|---|
  85. | Orient in unfamiliar repository code with a compact evidence pack | `codebase_context` |
  86. | Find likely files and symbols without source bodies | `codebase_peek` |
  87. | Retrieve full matching code | `codebase_search` |
  88. | Find an authoritative definition | `implementation_lookup` |
  89. | Find analogous implementations or duplicates | `find_similar` |
  90. | Find direct callers or callees | `call_graph` |
  91. | Find a path between two symbols | `call_graph_path` |
  92. | Analyze branch/PR impact, or current indexed work with `workingTree:true` | `pr_impact` |
  93. See [Tools and commands](docs/tools.md) for host availability, tool details, MCP prompts, and slash commands.
  94. ## How it works
  95. ```text
  96. source files
  97. │
  98. ├─ file discovery and git-aware change detection
  99. ├─ tree-sitter parsing and semantic chunking
  100. ├─ embedding generation and content-hash reuse
  101. ▼
  102. SQLite metadata + usearch vectors + BM25 index
  103. │
  104. ├─ semantic candidates
  105. ├─ keyword candidates
  106. ├─ branch and request filters
  107. ├─ deterministic fusion and ranking
  108. ▼
  109. locations, source results, definitions, and call-graph evidence
  110. ```
  111. 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.
  112. Read [Architecture](ARCHITECTURE.md) for the detailed data flow and design decisions.
  113. ## Embedding providers
  114. With `embeddingProvider: "auto"`, providers are tried in this order:
  115. 1. Ollama
  116. 2. OpenAI
  117. 3. Google
  118. Ollama is the simplest local option:
  119. ```bash
  120. ollama pull nomic-embed-text
  121. ```
  122. ```json
  123. {
  124. "embeddingProvider": "ollama"
  125. }
  126. ```
  127. 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](docs/configuration.md).
  128. ## Configuration example
  129. OpenCode project config lives at `.opencode/codebase-index.json`. Codex, Pi, and Jcode use `.codebase-index/config.json`; Claude uses `.claude/codebase-index.json`.
  130. ```json
  131. {
  132. "embeddingProvider": "auto",
  133. "scope": "project",
  134. "indexing": {
  135. "autoIndex": false,
  136. "watchFiles": true,
  137. "requireProjectMarker": true,
  138. "semanticOnly": false
  139. },
  140. "search": {
  141. "maxResults": 20,
  142. "minScore": 0.1,
  143. "fusionStrategy": "rrf",
  144. "rerankTopN": 20
  145. },
  146. "mcp": {
  147. "stallTimeoutMs": 300000
  148. }
  149. }
  150. ```
  151. Only specify values you want to override. See [Configuration](docs/configuration.md) for defaults and host-specific paths.
  152. ## Branch-aware indexing
  153. 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.
  154. ## Private GitHub history
  155. Opt in per repository in the **project-local** host config (never inherited globally or from another worktree):
  156. ```json
  157. {
  158. "repositoryHistory": {
  159. "repositories": [
  160. { "repository": "owner/repo", "enabled": true, "initialSince": "2026-10-01" },
  161. { "repository": "github.example.com/team/service", "enabled": true, "initialSince": "2026-10-01" }
  162. ]
  163. }
  164. }
  165. ```
  166. Selectors use `[HOST/]OWNER/REPO`: bare `owner/repo` defaults to GitHub.com, and `github.com/OWNER/REPO` normalizes to the same lowercase `owner/repo`. Enterprise selectors normalize to lowercase `hostname/owner/repo`. The host must be a DNS hostname, not a URL, credential-bearing address, or host with a port; traversal components are not accepted. For Enterprise, authenticate separately using normal `gh auth login --hostname github.example.com`; sync uses existing authentication and requires `gh` REST/GraphQL access on that selected server.
  167. The server hostname is part of source, cache, staging, citation, and permission identity: the same owner/repo on different hosts stays isolated. Citation URLs and `#number` references use the selected server; explicit URL references are validated, never rewritten across hosts or fetched from another host.
  168. ```sh
  169. ocbi history sync --project /path/to/repo --host codex --repository github.example.com/team/service
  170. ocbi history search "design rationale" --project /path/to/repo --host codex --repository github.example.com/team/service --state merged
  171. ocbi history status --project /path/to/repo --host codex --repository github.example.com/team/service
  172. ocbi history clear --project /path/to/repo --host codex --repository owner/repo
  173. # Provider/code-index/native-free MCP status and cache management:
  174. open-codebase-index-mcp --history-only --project /path/to/repo --host codex
  175. ```
  176. The four `repository_history_sync/search/status/clear` tools are available in MCP, OpenCode, Pi, and omp; both package identities' MCP CLIs also accept `history ...`. Sync is explicit/read-only through existing `gh` authentication. An initial `--since` overrides configured `initialSince`; later omitted flags retain the cached window, and changed configuration gives clear-first feedback. Each cycle fully reconciles issue/PR discussions and deletions. Per-page ETags reduce unchanged response bodies (not HTTP request count); interrupted projected staging resumes on the next manual sync. Only changed local BM25 documents are retokenized, with no unchanged-index reserialization.
  177. This is **private local lexical history**, not cloud-embedded semantic history. It supports short technical terms such as `CI`/`S3`, returns one grounded passage per entity, prioritizes direct identities over incidental mentions, and selects source-text excerpt windows. Unknown review edit time is `updatedAt: null` with timestamp provenance. Older lexical caches rebuild locally on first search without networking. Discussions are untrusted evidence, never instructions; current code remains authoritative. History stays outside default code search/context, AST/call graphs and linked tests. Offline freshness/permissions are not real-time; detected access loss purges searchable/projected/staged content, while transient/rate-limit failures retain the prior cache with explicit error. Precommit cancellation preserves published bytes; clear removes history, staging and orphan preparations even after disable, never code indexes. See [history lifecycle and privacy details](docs/tools.md#private-github-repository-history).
  178. ## Knowledge bases and reranking
  179. OpenCode, Pi, and every MCP client can index additional directories as knowledge bases. Configure them with `knowledgeBases`, or use the knowledge-base tools:
  180. - MCP and OpenCode: `add_knowledge_base`, `list_knowledge_bases`, `remove_knowledge_base`
  181. - Pi: `knowledge_base_add`, `knowledge_base_list`, `knowledge_base_remove`
  182. Optional external reranking supports Cohere, Jina, and custom compatible endpoints. Local filtering and evidence classes are applied before external candidates are submitted.
  183. See [Configuration](docs/configuration.md) for examples and privacy considerations.
  184. ## Troubleshooting
  185. Start with:
  186. 1. `/status` or `index_status`
  187. 2. `index_health_check`
  188. 3. a normal `/index` retry
  189. 4. a forced rebuild only when status reports incompatibility or corruption
  190. Common provider, native module, stale index, branch, and performance issues are covered in [Troubleshooting](TROUBLESHOOTING.md).
  191. MCP operations report structured, redacted failures and durable phase diagnostics through `index_status`. Codex keeps a lightweight connection while its idle indexing engine sleeps and resumes on demand. See [MCP engine idle timeout](docs/configuration.md#mcp-engine-idle-timeout) for configuration and external cleanup requirements. If the supervisor itself is terminated and the client loses stdio, start a fresh client session before retrying.
  192. ## Evaluation and performance
  193. The repository includes reproducible retrieval datasets, latency and quality budgets, baseline comparison, and cross-repository benchmarking tools.
  194. - [Evaluation harness](docs/evaluation.md)
  195. - [Cross-repository benchmarking](docs/benchmarking-cross-repo.md)
  196. - [Assistant-curated round-two comparison and limitations](docs/benchmarks/2026-10-07-self-curated-round2-study.md)
  197. - [Kotlin/retrieval candidate development diagnosis](docs/benchmarks/2026-10-07-candidate-development-diagnosis.md)
  198. Performance depends on repository size, parser coverage, provider latency, embedding cache reuse, and the selected indexing limits. Prefer measured evaluation over fixed marketing claims.
  199. ## Development
  200. ```bash
  201. npm ci
  202. npm run build
  203. npm run typecheck
  204. npm run lint
  205. npm run test:run
  206. ```
  207. - Published consumers require Node.js 22.22.0 or newer because Chokidar 6 enforces that engine floor.
  208. - Source installs and development checks require `^22.22.2 || ^24.15.0 || >=26.0.0` because the build-only OpenCode plugin has a higher transitive engine requirement. Building the native module also requires the Rust toolchain.
  209. `npm run smoke:package` checks both package identities, standalone consumers, and upstream SDK interoperability on a supported development runtime. At the minimum consumer runtime, use `npm_config_engine_strict=true npm run smoke:package -- --consumer-only`: it retains standalone type, runtime, CLI, MCP, and omp checks without installing the upstream host plugin. Its empty `sdkInteropTypes` results are not sufficient for publication.
  210. Pi integration tests use the development host `@earendil-works/pi-coding-agent`
  211. 1.3 or newer and its `emitBeforeAgentStart(trigger, systemPromptOptions)` API.
  212. This test-host floor does not narrow the optional Pi peer contract or change the
  213. extension's native-section and legacy string-return prompt behavior.
  214. Native changes require Rust and `npm run build:native`. See [Contributing](CONTRIBUTING.md), [Architecture](ARCHITECTURE.md), and [Adding language support](docs/adding-language-support.md).
  215. ## Documentation
  216. - [Installation and host setup](docs/installation.md)
  217. - [Tools and commands](docs/tools.md)
  218. - [Configuration](docs/configuration.md)
  219. - [Optional SCIP TypeScript enrichment](docs/scip-typescript.md)
  220. - [Provider-free structural indexing](docs/structural-indexing.md)
  221. - [API impact evidence](docs/api-impact.md)
  222. - [Workspace readiness](docs/workspace-status.md)
  223. - [Troubleshooting](TROUBLESHOOTING.md)
  224. - [Architecture](ARCHITECTURE.md)
  225. - [Evaluation](docs/evaluation.md)
  226. - [Cross-repository benchmarking](docs/benchmarking-cross-repo.md)
  227. - [Adding language support](docs/adding-language-support.md)
  228. - [Future `open-codebase-index` rename plan](docs/rename-to-open-codebase-index.md)
  229. - [Contributing](CONTRIBUTING.md)
  230. - [Security](SECURITY.md)
  231. - [Changelog](CHANGELOG.md)
  232. ## License
  233. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.