Code Search Tool Selector Skill

Code Search Tool Selector

This skill helps choose the most effective search tool for your task.

When Semantic Search Works Better

Claudemem provides better results for conceptual queries:

| Query Type | Example | Recommended Tool | |------------|---------|------------------| | "How does X work?" | "How does authentication work?" | claudemem search | | Find implementations | "Find all API endpoints" | claudemem search | | Architecture questions | "Map the service layer" | claudemem --agent map | | Trace data flow | "How does user data flow?" | claudemem search | | Audit integrations | "Audit Prime API usage" | claudemem search |

When Native Tools Work Better

| Query Type | Example | Recommended Tool | |------------|---------|------------------| | Exact string match | "Find 'DEPRECATED_FLAG'" | Grep | | Count occurrences | "How many TODO comments?" | Grep -c | | Specific symbol | "Find class UserService" | Grep | | File patterns | "Find all *.config.ts" | Glob |

Why Semantic Search is Often More Efficient

Token Efficiency: Reading 5 files costs ~5000 tokens; claudemem search costs ~500 tokens with ranked results.

Context Discovery: Claudemem finds related code you didn't know to ask for.

Ranking: Results sorted by relevance and PageRank, so important code comes first.

Example: Semantic Query

User asks: "How does authentication work?"

Less effective approach:

grep -r "auth" src/
# Result: 500 lines of noise, hard to understand

More effective approach:

claudemem status  # Check if indexed
claudemem search "authentication login flow JWT"
# Result: Top 10 semantically relevant code chunks, ranked

Quick Decision Guide

Classify the Task

| User Request | Category | Recommended Tool | |--------------|----------|------------------| | "Find all X", "How does X work" | Semantic | claudemem search | | "Audit X integration", "Map data flow" | Semantic | claudemem search | | "Understand architecture", "Trace X" | Semantic | claudemem map | | "Find exact string 'foo'" | Exact Match | Grep | | "Count occurrences of X" | Exact Match | Grep | | "Find symbol UserService" | Exact Match | Grep |

Step 2: Check claudemem Status (MANDATORY for Semantic)

# ALWAYS run this before semantic search
claudemem status

Interpret the output:

| Status | What It Means | Next Action | |--------|---------------|-------------| | Shows chunk count (e.g., "938 chunks") | ✅ Indexed | USE CLAUDEMEM (Step 3) | | "No index found" | ❌ Not indexed | Offer to index (Step 2b) | | "command not found" | ❌ Not installed | Fall back to Detective agent |

Step 2b: If Not Indexed, Offer to Index

AskUserQuestion({
  questions: [{
    question: "Claudemem is not indexed. Index now for better semantic search results?",
    header: "Index?",
    multiSelect: false,
    options: [
      { label: "Yes, index now (Recommended)", description: "Takes 1-2 minutes, enables semantic search" },
      { label: "No, use grep instead", description: "Faster but less accurate for semantic queries" }
    ]
  }]
})

If user says yes:

claudemem index -y

Step 3: Execute the Search

IF CLAUDEMEM IS INDEXED (from Step 2):

# Get role-specific guidance first
claudemem ai developer  # or architect, tester, debugger

# Then search semantically
claudemem search "authentication login JWT token validation" -n 15

IF CLAUDEMEM IS NOT AVAILABLE:

Use the detective agent:

Task({
  subagent_type: "code-analysis:detective",
  description: "Investigate [topic]",
  prompt: "Use semantic search to find..."
})

Tool Recommendations by Use Case

| Use Case | Less Efficient | More Efficient | |----------|----------------|----------------| | Semantic queries | grep -r "pattern" src/ | claudemem search "concept" | | Find implementations | Glob → Read all | claudemem search "feature" | | Understand flow | find . -name "*.ts" \| xargs... | claudemem --agent map |

Native tools (Grep, Glob, find) work well for exact matches but provide no semantic ranking.

When Hooks Redirect to Claudemem

If a hook provides claudemem results instead of native tool output:

Use the provided results - They're ranked by relevance
For more data - Run additional claudemem queries
Bypass available - Use _bypass_claudemem: true for native tools when needed

The hook system provides claudemem results proactively when the index is available.

Task-to-Tool Mapping Reference

| User Request | Native Approach | Semantic Approach (Recommended) | |--------------|-----------------|--------------------------------| | "Audit all API endpoints" | grep -r "router\|endpoint" | claudemem search "API endpoint route handler" | | "How does auth work?" | grep -r "auth\|login" | claudemem search "authentication login flow" | | "Find all database queries" | grep -r "prisma\|query" | claudemem search "database query SQL prisma" | | "Map the data flow" | grep -r "transform\|map" | claudemem search "data transformation pipeline" | | "What's the architecture?" | ls -la src/ | claudemem --agent map "architecture" | | "Find error handling" | grep -r "catch\|error" | claudemem search "error handling exception" | | "Trace user creation" | grep -r "createUser" | claudemem search "user creation registration" |

When Grep IS Appropriate

✅ Use Grep for:

Finding exact string: grep -r "DEPRECATED_FLAG" src/
Counting occurrences: grep -c "import React" src/**/*.tsx
Finding specific symbol: grep -r "class UserService" src/
Regex patterns: grep -r "TODO:\|FIXME:" src/

❌ Never use Grep for:

Understanding how something works
Finding implementations by concept
Architecture analysis
Tracing data flow
Auditing integrations

Integration with Detective Skills

After using this skill's decision tree, invoke the appropriate detective:

| Investigation Type | Detective Skill | |-------------------|-----------------| | Architecture patterns | code-analysis:architect-detective | | Implementation details | code-analysis:developer-detective | | Test coverage | code-analysis:tester-detective | | Bug root cause | code-analysis:debugger-detective | | Comprehensive audit | code-analysis:ultrathink-detective |

Quick Reference Card

┌─────────────────────────────────────────────────────────────────┐
│                    CODE SEARCH QUICK REFERENCE                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  1. ALWAYS check first:  claudemem status                       │
│                                                                  │
│  2. If indexed:          claudemem search "semantic query"       │
│                                                                  │
│  3. For exact matches:   Grep tool (only this case!)            │
│                                                                  │
│  4. For deep analysis:   Task(code-analysis:detective)          │
│                                                                  │
│  ⚠️ GREP IS FOR EXACT MATCHES, NOT SEMANTIC UNDERSTANDING       │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Pre-Investigation Checklist

Before ANY code investigation task, verify:

[ ] Ran claudemem status to check index
[ ] Classified task as SEMANTIC or EXACT MATCH
[ ] Selected appropriate tool based on classification
[ ] NOT using grep for semantic queries when claudemem is indexed

Multi-File Read Optimization

When reading multiple files, consider if a semantic search would be more efficient:

| Scenario | Optimization | |----------|-------------| | Read 3+ files in same directory | Try claudemem search first | | Glob with broad patterns | Try claudemem --agent map | | Sequential reads to "understand" | One semantic query may suffice |

Quick check before bulk reads:

Is claudemem indexed? (claudemem status)
Can this be one semantic query instead of N file reads?

Interception Examples

❌ About to do:

Read src/services/auth/login.ts
Read src/services/auth/session.ts
Read src/services/auth/jwt.ts
Read src/services/auth/middleware.ts
Read src/services/auth/types.ts
Read src/services/auth/utils.ts

✅ Do instead:

claudemem search "authentication login session JWT middleware" -n 15

❌ About to do:

Glob pattern: src/services/prime/**/*.ts
Then read all 12 matches sequentially

✅ Do instead:

claudemem search "Prime API integration service endpoints" -n 20

❌ Parallelization trap:

"Let me Read these 5 files while the detective agent works..."

✅ Do instead:

Trust the detective agent to use claudemem.
Don't duplicate work with inferior Read/Glob.

Efficiency Comparison

| Approach | Token Cost | Result Quality | |----------|------------|----------------| | Read 5+ files sequentially | ~5000 tokens | No ranking | | Glob → Read all matches | ~3000+ tokens | No semantic understanding | | claudemem search once | ~500 tokens | Ranked by relevance |

Tip: Claudemem results include context around matches, so you often don't need to read full files.

Recommended Workflow

Check index: claudemem status
Search semantically: claudemem search "concept query" -n 15
Read specific code: Use results to target file:line reads

This workflow finds relevant code faster than reading files sequentially.

Maintained by: MadAppGang Plugin: code-analysis v2.16.0 Purpose: Help choose the most efficient search tool for each task

Agent Skills: Code Search Tool Selector

Install this agent skill to your local

Skill Files