Osgrep

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.

Basic Search

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?"

Scoped Search

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