Skip to content
Back to search

osgrep

MarketplaceWorks with Claude CodeGitHub

Open Source Semantic Search for your AI Agent

Safety scan

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

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ryandonofrio3--osgrep/badge.svg)](/listings/ryandonofrio3--osgrep)

HTML

<a href="/listings/ryandonofrio3--osgrep"><img src="/api/listings/ryandonofrio3--osgrep/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

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

1. **Install**

   npm install -g osgrep

2. **Setup (Recommended)**

```bash osgrep setup ```

Downloads embedding models (~150MB) upfront. If you skip this, models download automatically on first use.

3. **Search**

```bash cd my-repo osgrep "where do we handle authentication?" ```

**Your first search will automatically index the repository.** Each repository is automatically isolated with its own index. Switching between repos "just works" — no manual configuration needed. If the background server is running (`osgrep serve`), search goes through the hot daemon; otherwise it falls back to on-demand indexing.

4. **Trace** (Call Graph)

```bash osgrep trace "function_name" ``` See who calls a function (upstream dependencies) and what it calls (downstream dependencies). Perfect for impact analysis and understanding code flow.

To find the symbols in your code base: ```bash osgrep symbols ```

In our public benchmarks, `osgrep` can save about 20% of your LLM tokens and deliver a 30% speedup.

<div align="center"> </div>

Claude Code Plugin

1. Run `osgrep install-claude-code` 2. Open Claude Code (`claude`) and ask it questions about your codebase. 3. Highly recommend indexing your code base before using the plugin. 4. The plugin's hooks auto-start `osgrep serve` in the background and shut it down on session end. Claude will use `osgrep` for semantic searches automatically but can be encouraged to do so.

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 · 21 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "osgrep",
  4. "owner": {
  5. "name": "Ryan D'Onofrio",
  6. "email": "ryandonofrio@gmail.com"
  7. },
  8. "plugins": [
  9. {
  10. "name": "osgrep",
  11. "source": "./plugins/osgrep",
  12. "description": "Semantic code search for Claude Code. Automatically indexes your project and provides intelligent search capabilities.",
  13. "version": "0.2.0",
  14. "author": {
  15. "name": "Ryan D'Onofrio",
  16. "email": "ryandonofrio@gmail.com"
  17. },
  18. "skills": ["./skills/osgrep"]
  19. }
  20. ]
  21. }
README.md · README · 330 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <h1>osgrep</h1>
  3. <p><em>Slash tokens. Save time. Semantic search for your coding agent.</em></p>
  4. <a href="https://opensource.org/licenses/Apache-2.0">
  5. <img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License: Apache 2.0" />
  6. </a>
  7. <a href="https://deepwiki.com/Ryandonofrio3/osgrep">
  8. <img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki" />
  9. </a>
  10. <a>
  11. <img alt="CodeRabbit Pull Request Reviews" src="https://img.shields.io/coderabbit/prs/github/ryandonofrio3/osgrep">
  12. </a>
  13. </div>
  14. Natural-language search that works like `grep`. Fast, local, and built for coding agents.
  15. - **Semantic:** Finds concepts ("where do transactions get created?"), not just strings.
  16. - **Call Graph Tracing:** Map dependencies with `trace` to see who calls what.
  17. - **Role Detection:** Distinguishes `ORCHESTRATION` (high-level logic) from `DEFINITION` (types/classes).
  18. - **Local & Private:** 100% local embeddings via `onnxruntime-node`.
  19. - **Auto-Isolated:** Each repository gets its own index automatically.
  20. - **Agent-Ready:** Native output with symbols, roles, and call graphs.
  21. ## Quick Start
  22. 1. **Install**
  23. ```bash
  24. npm install -g osgrep
  25. ```
  26. 2. **Setup (Recommended)**
  27. ```bash
  28. osgrep setup
  29. ```
  30. Downloads embedding models (~150MB) upfront. If you skip this, models download automatically on first use.
  31. 3. **Search**
  32. ```bash
  33. cd my-repo
  34. osgrep "where do we handle authentication?"
  35. ```
  36. **Your first search will automatically index the repository.** Each repository is automatically isolated with its own index. Switching between repos "just works" — no manual configuration needed. If the background server is running (`osgrep serve`), search goes through the hot daemon; otherwise it falls back to on-demand indexing.
  37. 4. **Trace** (Call Graph)
  38. ```bash
  39. osgrep trace "function_name"
  40. ```
  41. See who calls a function (upstream dependencies) and what it calls (downstream dependencies). Perfect for impact analysis and understanding code flow.
  42. To find the symbols in your code base:
  43. ```bash
  44. osgrep symbols
  45. ```
  46. In our public benchmarks, `osgrep` can save about 20% of your LLM tokens and deliver a 30% speedup.
  47. <div align="center">
  48. <img src="public/bench.png" alt="osgrep benchmark" width="100%" style="border-radius: 8px; margin: 20px 0;" />
  49. </div>
  50. ### Claude Code Plugin
  51. 1. Run `osgrep install-claude-code`
  52. 2. Open Claude Code (`claude`) and ask it questions about your codebase.
  53. 3. Highly recommend indexing your code base before using the plugin.
  54. 4. The plugin's hooks auto-start `osgrep serve` in the background and shut it down on session end. Claude will use `osgrep` for semantic searches automatically but can be encouraged to do so.
  55. ## Opencode Plugin
  56. 1. Run `osgrep install-opencode`
  57. 2. Open OC (`opencode`) and ask it questions about your codebase.
  58. 3. Highly recommend indexing your code base before using the plugin.
  59. 4. The plugin's hooks auto-start `osgrep serve` in the background and shut it down on session end. OC will use `osgrep` for semantic searches automatically but can be encouraged to do so.
  60. ## Commands
  61. ### `osgrep search`
  62. The default command. Searches the current directory using semantic meaning.
  63. ```bash
  64. osgrep "how is the database connection pooled?"
  65. ```
  66. **Options:**
  67. | Flag | Description | Default |
  68. | --- | --- | --- |
  69. | `-m <n>` | Max total results to return. | `25` |
  70. | `--per-file <n>` | Max matches to show per file. | `1` |
  71. | `-c`, `--content` | Show full chunk content instead of snippets. | `false` |
  72. | `--scores` | Show relevance scores (0-1) for each result. | `false` |
  73. | `--min-score <n>` | Filter out results below this score threshold. | `0` |
  74. | `--compact` | Show file paths only (like `grep -l`). | `false` |
  75. | `-s`, `--sync` | Force re-index changed files before searching. | `false` |
  76. | `-r`, `--reset` | Reset the index and re-index from scratch. | `false` |
  77. **Examples:**
  78. ```bash
  79. # General concept search
  80. osgrep "API rate limiting logic"
  81. # Deep dive (show more matches per file)
  82. osgrep "error handling" --per-file 5
  83. # Just give me the files
  84. osgrep "user validation" --compact
  85. # Show relevance scores and filter low-confidence matches
  86. osgrep "authentication" --scores --min-score 0.5
  87. ```
  88. ### `osgrep index`
  89. Manually indexes the repository. Useful if you want to pre-warm the cache or if you've made massive changes outside of the editor.
  90. - Respects `.gitignore` and `.osgrepignore` (see [Configuration](#ignoring-files) section).
  91. - **Smart Indexing:** Only embeds code and config files. Skips binaries, lockfiles, and minified assets.
  92. - **Bounded Concurrency:** Uses a fixed thread pool to keep your system responsive.
  93. - **Semantic Chunking:** Uses TreeSitter grammars for supported languages (TypeScript, JavaScript, Python, Go, Rust, C/C++, Java, C#, Ruby, PHP, JSON, YAML, Kotlin, Swift, Dart).
  94. **Options:**
  95. | Flag | Description | Default |
  96. | --- | --- | --- |
  97. | `-d`, `--dry-run` | See what would be indexed without making changes. | `false` |
  98. | `-p`, `--path <dir>` | Path to index (defaults to current directory). | `.` |
  99. | `-r`, `--reset` | Remove existing index and re-index from scratch. | `false` |
  100. | `-v`, `--verbose` | Show detailed progress with file names. | `false` |
  101. | `--allow-fallback` | Also index files without TreeSitter grammar support. | `false` |
  102. **Examples:**
  103. ```bash
  104. osgrep index # Index current dir
  105. osgrep index --dry-run # See what would be indexed
  106. osgrep index --verbose # Watch detailed progress (useful for debugging)
  107. osgrep index --allow-fallback # Include files without grammar support
  108. osgrep index --reset # Full re-index from scratch
  109. ```
  110. ### `osgrep serve`
  111. Runs a lightweight HTTP server with live file watching so searches stay hot in RAM.
  112. - Keeps LanceDB and the embedding worker resident for <50ms responses.
  113. - Watches the repo (via chokidar) and incrementally re-indexes on change.
  114. - Health endpoint: `GET /health`
  115. - Search endpoint: `POST /search` with `{ query, limit, path, rerank }`
  116. - Writes lock: `.osgrep/server.json` with `port`/`pid`
  117. **Options:**
  118. | Flag | Description |
  119. | --- | --- |
  120. | `-p, --port <port>` | Port to listen on (auto-increments if not specified) |
  121. | `-b, --background` | Run server in background and exit immediately |
  122. **Port Selection (priority order):**
  123. 1. Explicit `-p <port>` flag
  124. 2. `OSGREP_PORT` environment variable
  125. 3. Auto-increment from registry (last used port + 1, or 4444 if no servers)
  126. **Usage:**
  127. ```bash
  128. osgrep serve # Foreground, port 4444 (or next available)
  129. osgrep serve --background # Background mode, auto port
  130. osgrep serve -b -p 5000 # Background on specific port
  131. ```
  132. **Subcommands:**
  133. ```bash
  134. osgrep serve status # Show server status for current directory
  135. osgrep serve stop # Stop server in current directory
  136. osgrep serve stop --all # Stop all running osgrep servers
  137. ```
  138. **Example workflow:**
  139. ```bash
  140. # Start servers in multiple projects
  141. cd ~/project-a && osgrep serve -b # Starts on port 4444
  142. cd ~/project-b && osgrep serve -b # Starts on port 4445 (auto-increment)
  143. # Check status
  144. osgrep serve status
  145. # Stop all when done
  146. osgrep serve stop --all
  147. ```
  148. Claude Code hooks start/stop this automatically; you rarely need to run it manually.
  149. ### `osgrep list`
  150. Lists all indexed repositories (stores) and their metadata.
  151. ```bash
  152. osgrep list
  153. ```
  154. Shows store names, sizes, and last modified times. Useful for seeing what's indexed and cleaning up old stores.
  155. ### `osgrep skeleton`
  156. Generates a compressed "skeleton" of a file, showing only signatures, types, and class structures while eliding function bodies.
  157. ```bash
  158. osgrep skeleton src/lib/auth.ts
  159. ```
  160. **Output:**
  161. ```typescript
  162. class AuthService {
  163. validate(token: string): boolean {
  164. // → jwt.verify, checkScope, .. | C:5 | ORCH
  165. }
  166. }
  167. ```
  168. **Modes:**
  169. - `osgrep skeleton <file>`: Skeletonize specific file.
  170. - `osgrep skeleton <Symbol>`: Find symbol in index and skeletonize its file.
  171. - `osgrep skeleton "query"`: Search for query and skeletonize top matches.
  172. **Supported Languages:**
  173. TypeScript, JavaScript, Python, Go, Rust, Java, C#, C++, C, Ruby, PHP.
  174. ### `osgrep doctor`
  175. Checks installation health, model paths, and database integrity.
  176. ```bash
  177. osgrep doctor
  178. ```
  179. ## Performance & Architecture
  180. osgrep is designed to be a "good citizen" on your machine:
  181. 1. **Bounded Concurrency:** Chunking/embedding stay within small thread pools (1–4) and capped batch sizes to keep laptops responsive.
  182. 2. **Smart Chunking:** Uses `tree-sitter` to split code by function/class boundaries, ensuring embeddings capture complete logical blocks.
  183. 3. **Deduplication:** Identical code blocks (boilerplate, license headers) are embedded once and cached, saving space and time.
  184. 4. **Semantic Split Search:** Queries both "Code" and "Docs" separately to ensure documentation doesn't drown out implementation details, then reranks with ColBERT.
  185. 5. **Global Batching:** A producer/consumer pipeline decouples chunking from embedding. Files are chunked concurrently, queued, embedded in fat batches, and written to LanceDB in bulk.
  186. 6. **Anchor-Only Scans & Batch Deletes:** File discovery and stale cleanup hit only anchor rows, and stale/changed paths are removed with a single `IN` delete to minimize I/O.
  187. 7. **Structural Boosting:** Function/class chunks get a small score boost; test/spec paths are slightly downweighted to bubble up primary definitions first.
  188. 8. **Role Classification:** Detects `ORCHESTRATION` functions (high complexity, many calls) vs `DEFINITION` (types/classes) to help agents prioritize where to read.
  189. ## Configuration
  190. ### Automatic Repository Isolation
  191. osgrep automatically creates a unique index for each repository based on:
  192. 1. **Git Remote URL** (e.g., `github.com/facebook/react` → `facebook-react`)
  193. 2. **Git Repo without Remote** → directory name + hash (e.g., `utils-7f8a2b3c`)
  194. 3. **Non-Git Directory** → directory name + hash for collision safety
  195. **Examples:**
  196. ```bash
  197. cd ~/work/myproject # Auto-detected: owner-myproject
  198. osgrep "API handlers"
  199. cd ~/personal/utils # Auto-detected: utils-abc12345
  200. osgrep "helper functions"
  201. ```
  202. Stores are isolated automatically — no manual `--store` flags needed!
  203. ### Ignoring Files
  204. osgrep respects both `.gitignore` and `.osgrepignore` files when indexing. Create a `.osgrepignore` file in your repository root to exclude additional files or patterns from indexing.
  205. **`.osgrepignore` syntax:**
  206. - Uses the same pattern syntax as `.gitignore`
  207. - Patterns are relative to the repository root
  208. - Supports glob patterns, negation (`!`), and directory patterns (`/`)
  209. ### Manual Store Management
  210. - **View all stores:** `osgrep list`
  211. - **Override auto-detection:** `osgrep --store custom-name "query"`
  212. - **Clean up old stores:** `rm -rf ~/.osgrep/data/store-name`
  213. - **Data location:** `~/.osgrep/data`
  214. ## Development
  215. ```bash
  216. pnpm install
  217. pnpm build # or pnpm dev
  218. pnpm format # biome check
  219. ```
  220. ## Troubleshooting
  221. - **Index feels stale?** Run `osgrep index` to refresh.
  222. - **Weird results?** Run `osgrep doctor` to verify models.
  223. - **Index getting stuck?** Run `osgrep index --verbose` to see which file is being processed.
  224. - **Want faster indexing?** Keep fallback disabled (default) to skip files without TreeSitter support.
  225. - **Need a fresh start?** Delete `~/.osgrep/data` and `~/.osgrep/meta.json` and run `osgrep index`.
  226. ## Attribution
  227. osgrep is built upon the foundation of [mgrep](https://github.com/mixedbread-ai/mgrep) by MixedBread. We acknowledge and appreciate the original architectural concepts and design decisions that informed this work.
  228. See the [NOTICE](NOTICE) file for detailed attribution information.
  229. ## License
  230. Licensed under the Apache License, Version 2.0.
  231. See [LICENSE](LICENSE) and [Apache-2.0](https://opensource.org/licenses/Apache-2.0) for details.

Ratings and comments

Sign in to rate this skill.

Sign in

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