ogrep
Semantic grep for codebases — local-first, SQLite-backed, with agentic Claude Code integration.
ogrep helps you search code by meaning, not just keywords. It builds a local semantic index (.ogrep/index.sqlite by default) and retrieves the most relevant code chunks for questions like:
- "where is authentication handled?"
- "how are API errors mapped to exceptions?"
- "where do we open DB connections and run queries?"
- "what kind of API key mechanism do we use?"
GitHub: github.com/gplv2/ogrep-marketplace
Website: ogrep.be — quick overview
What's New
v0.9.0: Agentic Semantic Search
ogrep now runs as a dedicated Claude Code subagent — dispatched automatically when Claude encounters conceptual code questions. This is a fundamental shift from passive skill to active agent.
What changed:
- Agent architecture: ogrep registers as a
subagent_type (like episodic-memory), running in its own context window with a specialized system prompt
- Summarize → Narrow → Drill: The agent follows a mandatory three-step workflow — cheap
--summarize overview first, narrow to relevant files, then expand specific chunks. Saves ~85% tokens vs raw results
- Clean context: The agent processes JSON output internally and returns synthesized findings with
file:line references. No raw JSON in your conversation
- Skill as router: The skill is now a lightweight dispatcher (48 lines) that tells Claude when to use ogrep. All search logic lives in the agent
Why it matters: Claude now dispatches ogrep at the right moment for conceptual questions, without manual invocation. The agent handles the full search workflow autonomously and returns concise, actionable results.
v0.8.x: AST Chunking, Voyage AI, FlashRank
v0.8.9: Optimized Skill
Trimmed skill definition from 548 to 180 lines (67% reduction). Better trigger accuracy with explicit negative examples.
v0.8.1: AST Chunking Now Default
AST-aware chunking is now enabled by default when tree-sitter is available. This produces semantically coherent chunks (complete functions, classes) instead of arbitrary line breaks.
--ast flag removed (now default behavior)--no-ast flag added to explicitly disable- Auto-detection: uses AST when tree-sitter is installed, falls back silently otherwise
pip install "ogrep[ast]" # Enable AST support
ogrep index . # AST enabled automatically
ogrep index . --no-ast # Explicitly disable
v0.8.0: Voyage AI Integration & Benchmark Findings
Voyage AI (Recommended for Code Search)
Voyage AI's voyage-code-3 achieves best search quality in our benchmarks:
| Configuration | Hit@1 | MRR | Cost |
|---|
| Voyage voyage-code-3 | 7/10 | 0.717 | $0.06/M |
| OpenAI text-embedding-3-small | 6/10 | 0.700 | $0.02/M |
| Nomic (local) + flashrank | 6/10 | 0.633 | Free |
pip install "ogrep[voyage]"
export VOYAGE_API_KEY="pa-..."
ogrep index . -m voyage-code-3
Key Finding: Skip Reranking with Quality Embeddings
Reranking degrades results when using high-quality embeddings:
| Embedding | Without Rerank | With Rerank | Action |
|---|
| Voyage | 0.717 MRR | 0.593 (-17%) | ❌ Don't rerank |
| OpenAI | 0.700 MRR | 0.550 (-21%) | ❌ Don't rerank |
| Nomic (local) | 0.545 MRR | 0.633 (+16%) | ✅ Use reranking |
The rule: Reranking helps weak embeddings but hurts strong ones.
FlashRank as Default Reranker
When reranking is needed, FlashRank is now the default:
- Lightweight: ~4MB (vs ~300MB for PyTorch models)
- Parallel-safe: No file locking needed (ONNX runtime)
- Fast: ~200ms per query on CPU
v0.7.4: Path Filtering, Summary Mode, Confidence Scoring
- Path filtering:
--glob "*.py" and --exclude "tests/*"
- Summary mode:
--summarize for file-level aggregation (~85% token savings)
- Hybrid confidence scoring: Combines relative position + absolute quality
v0.7.3: Branch-Aware Indexing
- Automatic branch tracking prevents stale results when switching branches
- Cross-branch queries:
ogrep query "auth" --branch main
- Embedding reuse across branches via content addressing
Breaking Changes
- v0.8.1:
--ast flag removed (AST is now default)
- v0.7.2: JSON output is now default (use
--no-json for text)
Installation
Option A: pip (recommended)
pip install ogrep
Option B: pipx (isolated environment)
pipx install ogrep
Note: pipx sometimes has issues. If you encounter problems, use pip instead.
Option C: Claude Code Marketplace + Plugin
# Add the marketplace
/plugin marketplace add gplv2/ogrep-marketplace
# Install the plugin
/plugin install ogrep@ogrep-marketplace
gplv2