codebase-navigator

name	codebase-navigator
description	Semantic code search using osgrep for understanding codebases, finding implementations, and navigating large projects. Use when asked "where is", "how does", "find the code that", or any question about code location or implementation.

Codebase Navigator

Semantic code search powered by osgrep - find code by meaning, not just keywords.

When to Use

Invoke when user:

• Asks "where is [feature] implemented?"
• Asks "how does [component] work?"
• Wants to "find the code that handles [task]"
• Needs to understand codebase architecture
• Searches for implementation patterns

Core Workflow

1. Check Index Freshness (Auto-Refresh)

Before searching, check if index is stale (>4 hours):

# Find store for current repo
osgrep list

# Check age of relevant store (macOS)
STORE=~/.osgrep/data/YOUR-STORE.lance
STORE_AGE=$(( $(date +%s) - $(stat -f %m "$STORE") ))

# If older than 4 hours (14400 seconds), refresh
if [ $STORE_AGE -gt 14400 ]; then
  echo "Index is $(( STORE_AGE / 3600 )) hours old - refreshing..."
  osgrep index
fi

Quick version: If unsure, just use --sync:

osgrep search "query" --sync   # Always safe, updates before searching

2. First-Time Setup

If no store exists for current repo:

osgrep list              # See available stores
osgrep doctor            # Verify setup is healthy
osgrep index             # Index current directory (takes ~30s-2min)

3. Search Semantically

Basic search:

osgrep search "natural language description of what you're looking for"

Tuned search:

osgrep search "query" --max-count 10      # Limit total results
osgrep search "query" --per-file 3        # Multiple matches per file
osgrep search "query" --content           # Show full chunk content
osgrep search "query" --compact           # File paths only
osgrep search "query" --scores            # Show relevance scores
osgrep search "query" --json              # Machine-readable output

3. Synthesize Results

DO NOT dump raw osgrep output. Instead:

1. Read the relevant file snippets
2. Understand the code in context
3. Explain to user in plain language
4. Cite specific files and line numbers

Query Formulation

Semantic queries work best. Transform user questions:

User asks	osgrep query
"Where's the auth?"	"authentication logic and user login"
"How do we handle errors?"	"error handling and exception management"
"Find the API endpoints"	"HTTP routes and API endpoint definitions"
"Database queries"	"database queries and SQL execution"
"Config loading"	"configuration loading and environment variables"

Tips for better queries:

• Use descriptive phrases, not keywords
• Include synonyms: "auth" → "authentication logic and user login"
• Describe the purpose: "code that validates user input"
• Be specific about what you want: "function that calculates total price"

Output Modes

Default Mode

Shows snippet preview with line numbers:

📂 src/auth/login.ts
   1 │ export async function login(username: string, password: string) {
   2 │   const user = await findUser(username);

Content Mode (--content)

Shows full chunk content for deeper context.

Compact Mode (--compact)

File paths only - useful for getting quick overview:

📂 src/auth/login.ts
📂 src/auth/session.ts
📂 src/middleware/auth.ts

JSON Mode (--json)

Machine-readable for programmatic use.

Scores Mode (--scores)

Shows relevance scores (0-1) - useful for understanding match quality.

Advanced Usage

Keep Index Fresh

osgrep indexes can become stale. Refresh regularly, especially after:

• Pulling new code
• Creating/deleting files
• Major refactoring

osgrep search "query" --sync    # Update index then search
osgrep index                    # Full re-index if --sync isn't enough

Symptom of stale index: Known files not appearing in results, or deleted files still showing up.

Background Server

For large codebases with frequent changes:

osgrep serve                    # Runs on port 4444
osgrep serve --port 8080        # Custom port

Multiple Stores

Work with specific indexed stores:

osgrep --store myproject.lance search "query"

Query Refinement

When first search returns too many/wrong results:

Step 1: Check result quality

osgrep search "query" --scores  # Low scores (<0.15) = poor matches

Step 2: Narrow with domain terms

❌ "packaging workflow" → finds ArtifactsBuilder, MCPBuilder
✅ "skill packaging automation" → finds SkillPackager

Step 3: Add specificity

❌ "validation" → too broad (25+ files)
✅ "YAML frontmatter validation for skills" → targeted

Step 4: Try synonyms if nothing found

❌ "auth" → too terse
✅ "authentication login session user credentials" → covers variations

osgrep vs grep: Decision Guide

Use osgrep when...	Use grep/rg when...
Searching by concept	Searching for exact strings
"Where is auth handled?"	"Find TODO:"
"How does caching work?"	"Find sha256"
Unknown function names	Known function names
Architecture questions	Error message lookup
Understanding code purpose	Finding specific identifiers

Rule of thumb: If you could type the exact string, use grep. If you're describing what code does, use osgrep.

Combining Tools

osgrep + Glob (file types)

osgrep finds code that mentions Python, not just .py files:

# Find Python data processing
osgrep search "python data processing" --compact  # May include .md files
# Then filter:
# Use Glob tool with pattern "**/*.py" for actual scripts

osgrep + grep (refine)

# Step 1: Find relevant area
osgrep search "checksum verification"  # May miss literal "sha256"

# Step 2: grep for specific term
grep -r "sha256" --include="*.sh"  # Finds exact matches

osgrep + Read (understand)

# Step 1: Find files
osgrep search "error handling middleware" --compact

# Step 2: Read to understand
# Use Read tool on top results

Anti-Patterns

DON'T:

• Use osgrep for exact string matches (use grep/rg instead)
• Dump raw output without synthesis
• Skip indexing and wonder why searches fail
• Use single keywords ("auth") instead of phrases ("authentication handling")
• Expect osgrep to find technical literals like "sha256", "TODO:", error codes

DO:

• Formulate queries as natural language descriptions
• Check osgrep list if searches return nothing
• Use --content when you need more context
• Combine with file reading for full understanding
• Use --scores to assess match quality
• Refine queries iteratively when results are poor

Example Session

User: "Where do we calculate shipping costs?"

Process:

osgrep search "shipping cost calculation and pricing logic"

Results show: src/orders/shipping.ts, src/utils/pricing.ts

Response: "Shipping costs are calculated in src/orders/shipping.ts:45-67, which uses the calculateShipping() function. This calls pricing utilities from src/utils/pricing.ts for rate lookups. The calculation considers weight, distance, and shipping method."

References

For query patterns and examples:

• references/query-patterns.md - Common query formulations
• references/troubleshooting.md - Common issues and fixes