osgrep

Ryandonofrio3's avatarfrom Ryandonofrio3

Semantic code search. Use alongside grep - grep for exact strings, osgrep for concepts.

⭐867stars🔀49forks📁View on GitHub🕐Updated Dec 15, 2025
[Developer Tools]

When & Why to Use This Skill

osgrep is an advanced semantic code search tool designed to help developers and AI agents navigate complex codebases by searching for concepts and intent rather than just literal strings. By leveraging AI-powered indexing, it allows users to ask natural language questions like 'where is authentication handled?' to find relevant logic, orchestration points, and call graphs, significantly reducing the time spent on manual code exploration.

Use Cases

  • Architectural Mapping: Quickly identify entry points and core logic for specific features in a large, unfamiliar codebase by searching for high-level concepts.
  • Call Graph Analysis: Trace the flow of execution by identifying which functions call a specific method and what that method interacts with, aiding in impact analysis.
  • Efficient Code Navigation: Use 'skeleton' views and line-range reading to understand 2000+ line files without overwhelming the context window with unnecessary code.
  • Onboarding and Knowledge Transfer: Help new team members understand how different modules coordinate by searching for the 'ORCHESTRATION' logic behind specific business requirements.
nameosgrep
descriptionSemantic code search. Use alongside grep - grep for exact strings, osgrep for concepts.
allowed-tools"Bash(osgrep:*), Read"

What osgrep does

Finds code by meaning. When you'd ask a colleague "where do we handle auth?", use osgrep.

  • grep/ripgrep: exact string match, fast
  • osgrep: concept match, finds code you couldn't grep for

Primary command

osgrep "where do we validate user permissions"

Returns ~10 results with code snippets (15+ lines each). Usually enough to understand what's happening.

Output explained

ORCHESTRATION src/auth/handler.ts:45
Defines: handleAuth | Calls: validate, checkRole, respond | Score: .94

export async function handleAuth(req: Request) {
  const token = req.headers.get("Authorization");
  const claims = await validateToken(token);
  if (!claims) return unauthorized();
  const allowed = await checkRole(claims.role, req.path);
  ...
  • ORCHESTRATION = contains logic, coordinates other code
  • DEFINITION = types, interfaces, classes
  • Score = relevance (1 = best match)
  • Calls = what this code calls (helps you trace flow)

When to Read more

The snippet often has enough context. But if you need more:

# osgrep found src/auth/handler.ts:45-90 as ORCH
Read src/auth/handler.ts:45-120

Read the specific line range, not the whole file.

Other commands

# Trace call graph (who calls X, what X calls)
osgrep trace handleAuth

# Skeleton of a huge file (to find which ranges to read)
osgrep skeleton src/giant-2000-line-file.ts

# Just file paths when you only need locations
osgrep "authentication" --compact

Workflow: architecture questions

# 1. Find entry points
osgrep "where do requests enter the server"
# Review the ORCH results - code is shown

# 2. If you need deeper context on a specific function
Read src/server/handler.ts:45-120

# 3. Trace to understand call flow
osgrep trace handleRequest

Tips

  • More words = better results. "auth" is vague. "where does the server validate JWT tokens" is specific.
  • ORCH results contain the logic - prioritize these
  • Don't read entire files. Use the line ranges osgrep gives you.
  • If results seem off, rephrase your query like you'd ask a teammate

If Index is Building

If you see "Indexing" or "Syncing": STOP. Tell the user the index is building. Ask if they want to wait or proceed with partial results.