osgrep

Natural-language search that works like grep. Fast, local, and built for coding agents.

• Semantic: Finds concepts ("where do transactions get created?"), not just strings.
• Call Graph Tracing: Map dependencies with trace to see who calls what.
• Role Detection: Distinguishes ORCHESTRATION (high-level logic) from DEFINITION (types/classes).
• Local & Private: 100% local embeddings via onnxruntime-node.
• Auto-Isolated: Each repository gets its own index automatically.
• Agent-Ready: Native output with symbols, roles, and call graphs.

Quick Start

1. Install

   npm install -g osgrep
   

2. Setup (Recommended)

   osgrep setup
   

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

3. Search

   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)

   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.

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.

Opencode Plugin

1. Run osgrep install-opencode
2. Open OC (opencode) 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. OC will use osgrep for semantic searches automatically but can be encouraged to do so.

Commands

osgrep search

The default command. Searches the current directory using semantic meaning.

osgrep "how is the database connection pooled?"

Options:

Flag	Description	Default
-m <n>	Max total results to return.	25
--per-file <n>	Max matches to show per file.	1
-c, --content	Show full chunk content instead of snippets.	false
--scores	Show relevance scores (0-1) for each result.	false
--min-score <n>	Filter out results below this score threshold.	0
--compact	Show file paths only (like grep -l).	false
-s, --sync	Force re-index changed files before searching.	false
-r, --reset	Reset the index and re-index from scratch.	false
Examples:

# General concept search
osgrep "API rate limiting logic"

# Deep dive (show more matches per file)
osgrep "error handling" --per-file 5

# Just give me the files
osgrep "user validation" --compact

# Show relevance scores and filter low-confidence matches
osgrep "authentication" --scores --min-score 0.5

osgrep index

Manually indexes the repository. Useful if you want to pre-warm the cache or if you've made massive changes outside of the editor.

• Respects .gitignore and .osgrepignore (see Configuration section).
• Smart Indexing: Only embeds code and config files. Skips binaries, lockfiles, and minified assets.
• Bounded Concurrency: Uses a fixed thread pool to keep your system responsive.
• Semantic Chunking: Uses TreeSitter grammars for supported languages (TypeScript, JavaScript, Python, Go, Rust, C/C++, Java, C#, Ruby, PHP, JSON, YAML, Kotlin, Swift, Dart).

Options: