search-interceptor

name	search-interceptor
description	💡 Bulk file read optimizer. Suggests semantic search alternatives when reading multiple files. Helps reduce token usage by using claudemem's ranked results instead of sequential file reads.
allowed-tools	Bash, AskUserQuestion

Search Interceptor

This skill helps optimize bulk file operations by suggesting semantic search alternatives when they would be more efficient.

When Semantic Search is More Efficient

Scenario	Token Cost	Alternative
Read 5+ files	~5000 tokens	claudemem search (~500 tokens)
Glob all *.ts files	~3000+ tokens	claudemem --agent map
Sequential reads to understand	Variable	One semantic query

When to Consider Alternatives

Multiple File Reads

If planning to read several files, consider:

# Instead of reading 5 files individually
claudemem search "concept from those files" -n 15
# Gets ranked results with context

Broad Glob Patterns

If using patterns like src/**/*.ts:

# Instead of globbing and reading all matches
claudemem --agent map "what you're looking for"
# Gets structural overview with PageRank ranking

File Paths Mentioned in Task

Even when specific paths are mentioned, semantic search often finds additional relevant code:

claudemem search "concept related to mentioned files"

---

Interception Protocol

Step 1: Pause Before Execution

When you're about to execute bulk file operations, STOP and run:

claudemem status

Step 2: Evaluate

If claudemem is indexed:

Your Plan	Better Alternative
Read 5 auth files	claudemem search "authentication login session"
Glob all services	claudemem search "service layer business logic"
Read mentioned paths	claudemem search "[concept from those paths]"

If claudemem is NOT indexed:

claudemem index -y

Then proceed with semantic search.

Step 3: Execute Better Alternative

# Instead of reading N files, run ONE semantic query
claudemem search "concept describing what you need" -n 15

# ONLY THEN read specific lines from results

---

Interception Decision Matrix

Situation	Intercept?	Action
Read 1-2 specific files	No	Proceed with Read
Read 3+ files in investigation	YES	Convert to claudemem search
Glob for exact filename	No	Proceed with Glob
Glob for pattern discovery	YES	Convert to claudemem search
Grep for exact string	No	Proceed with Grep
Grep for semantic concept	YES	Convert to claudemem search
Files mentioned in prompt	YES	Search semantically first

---

Examples of Interception

Example 1: Auth Investigation

❌ Original plan:

I see the task mentions auth, let me read:
- src/services/auth/login.ts
- src/services/auth/session.ts
- src/services/auth/jwt.ts
- src/services/auth/middleware.ts
- src/services/auth/utils.ts

✅ After interception:

claudemem status  # Check if indexed
claudemem search "authentication login session JWT token validation" -n 15
# Now I have ranked, relevant chunks instead of 5 full files

Example 2: API Integration Audit

❌ Original plan:

Audit mentions Prime API files:
- src/services/prime/internal_api/client.ts
- src/services/prime/api.ts
Let me just Read these directly...

✅ After interception:

claudemem search "Prime API integration endpoints HTTP client" -n 20
# This finds ALL Prime-related code, ranked by relevance
# Not just the 2 files mentioned

Example 3: Pattern Discovery

❌ Original plan:

Glob("src/**/*.controller.ts")
Then read all 15 controllers to understand routing

✅ After interception:

claudemem search "HTTP controller endpoint route handler" -n 20
# Gets the most relevant routing code, not all controllers

---

Why Semantic Search Often Works Better

Native Tools	Semantic Search
No ranking	Ranked by relevance + PageRank
No relationships	Shows code connections
~5000 tokens for 5 files	~500 tokens for ranked results
Only explicitly requested code	Discovers related code

Tip: For investigation tasks, try claudemem search first to get a ranked view of relevant code.

---

Integration with Other Skills

This skill works with:

Skill	Relationship
code-search-selector	Selector determines WHAT tool; Interceptor validates BEFORE execution
claudemem-search	Interceptor redirects to claudemem; this skill shows HOW to search
deep-analysis	Interceptor prevents bad patterns; deep-analysis uses good patterns
Detective skills	Interceptor prevents duplicate work by trusting detective agents

---

Hook System Integration

The hook system may provide claudemem results proactively when the index is available:

• Grep queries → May receive claudemem search results instead
• Bulk reads → May receive suggestion to use semantic search
• Broad globs → May receive map results

Using the Bypass Flag

When you specifically need native tool behavior:

{ "pattern": "exact string", "_bypass_claudemem": true }

This tells hooks you intentionally want native tool output.

---

Quick Reference

Before bulk Read/Glob operations, consider:

1. Is claudemem indexed? → claudemem status
2. Can this be one semantic query? → Often yes
3. Do you need exact matches? → Use native tools with bypass flag

General guideline: For understanding/investigation, try semantic search first. For exact matches, use native tools.

---

Maintained by: MadAppGang Plugin: code-analysis v2.16.0 Purpose: Help optimize bulk file operations with semantic search alternatives