osgrep-semantic-search

name	osgrep-semantic-search
description	Semantic code search via the `osgrep` CLI. Use when the user wants to find code by behavior, concept, or intent ("where do we validate JWTs?", "where is rate limiting handled?") rather than by exact text. Prefer ripgrep for literal matches and ast-grep for structural patterns.

Use the `osgrep` CLI to perform semantic code search against an indexed repository.

The MCP-server form of osgrep (osgrep mcp / osgrep serve) is intentionally NOT used by this skill. It spawns multiple worker processes that consume gigabytes of RAM and pin every CPU core, which has caused thermal throttling and OOM pressure in practice. The CLI is the supported interface.

<when_to_use> Use osgrep when:

• The user describes behavior or intent, not an exact identifier ("where do we throttle requests", "find the JWT verification path", "what code parses the config file")
• A previous ripgrep / ast-grep search came back too noisy or too narrow
• You need to discover related code spread across files, modules, or layers
• You want to map an unfamiliar subsystem before drilling in with Read

Do NOT use osgrep when:

• You already know the exact symbol or file → use Read / rg
• You want a structural code pattern → use ast-grep
• You only want filename discovery → use rg --files or fd
• The repo has no index and indexing would take longer than a manual search </when_to_use>

<cli_reference> Top-level commands (verify with osgrep --help):

Command	Purpose
osgrep index	One-time / refresh index for current repo

Verify an index exists for the repo root: Phrase the query as **behavior or concept**, not as a symbol name: If too broad, scope by path or add concrete anchors: Treat returned hits as anchors. Then drill in with `Read`, `rg`, or `ast-grep` for precise follow-up. For symbol-level questions, prefer the targeted subcommands: - NEVER run `osgrep mcp` or `osgrep serve` from this skill. Both start long-lived background processes that consume significant RAM and CPU. - Always pass `--plain` when capturing output for further reasoning. - Re-index after large refactors or when results look stale. - If `osgrep` is not installed in the environment, fall back to ripgrep / ast-grep and tell the user osgrep is unavailable. - Indexing is a write to `.osgrep/` — do not run it inside read-only or ephemeral checkouts. - Structure / AST queries → `ast-grep` - Literal text / identifier → `ripgrep` (`rg`) - Repo layout discovery → `workflows/repo-discovery.md` in the `code-search` skill (if loaded)