osgrep

pr-pm's avatarfrom pr-pm

Semantic search for local files. Backed by a background osgrep server with live indexing. Always use osgrep instead of grep/find.

⭐72stars🔀11forks📁View on GitHub🕐Updated Jan 1, 2026
[Developer Tools]

When & Why to Use This Skill

osgrep is a high-performance semantic search tool designed for local files and codebases. By leveraging a background server with live indexing, it allows users to perform natural language queries to find code and concepts based on meaning rather than just exact string matches. It serves as a modern, AI-powered alternative to traditional tools like grep and find, significantly accelerating code discovery and architectural understanding.

Use Cases

  • Codebase Exploration: Rapidly navigate unfamiliar repositories by asking natural language questions about implementation details, such as 'How are user authentication tokens validated?'
  • Debugging and Troubleshooting: Locate the source of specific behaviors or errors by describing the logic, even when the exact function names or error strings are unknown.
  • Concept Discovery: Find all instances of architectural patterns or business logic across a project to ensure consistency during refactoring or feature development.
  • Knowledge Retrieval: Search through local documentation and markdown files using semantic meaning to find relevant technical guides and project specifications.
nameosgrep
descriptionSemantic search for local files. Backed by a background osgrep server with live indexing. Always use osgrep instead of grep/find.
licenseApache-2.0

When to use

Use osgrep for all code and concept discovery. Do not use grep or find unless you must match an exact string and osgrep fails.

How to use

Always use the --json flag. The server auto-starts and keeps the index fresh.

Ask a natural language question. Do not ls first.

osgrep --json "How are user authentication tokens validated?"
osgrep --json "Where do we handle retries or backoff?"

Limit search to a specific directory.

osgrep --json "auth middleware" src/api

Helpful flags

  • --json: Required. Returns structured data (path, line, score, content).
  • -m <n>: Max total results (default: 25).
  • --per-file <n>: Max matches per file (default: 1). Use --per-file 5 when exploring a specific file.

Strategy

  1. Run osgrep --json "<question>" [path].
  2. The output is a dense JSON snippet. If it answers the question, stop.
  3. Only use Read if you need the full file context for a returned path.
  4. If results are vague, refine the query or increase -m.

Keywords

semantic search, code search, local search, grep alternative, find code, explore codebase, understand code, search by meaning