search-interceptor
⛔ INTERCEPT TRIGGER: Automatically invoked BEFORE Read 3+ files OR Glob with broad patterns. Validates whether bulk file operations should be replaced with semantic search. Prevents token waste from sequential file reads.
When & Why to Use This Skill
The Search Interceptor is a high-efficiency Claude skill designed to optimize bulk file operations and minimize token consumption. It acts as a smart gateway that intercepts requests to read multiple files or broad glob patterns, suggesting semantic search alternatives via claudemem. By replacing sequential file reads with ranked, context-aware results, it significantly enhances the agent's performance during large-scale code analysis and investigation tasks.
Use Cases
- Token Cost Reduction: Automatically prevents expensive bulk file reads (e.g., 5+ files) by redirecting the agent to semantic search, potentially reducing token usage by up to 90%.
- Large-Scale Codebase Exploration: Streamlines the process of understanding complex architectures by providing a ranked overview of relevant code chunks rather than overwhelming the context window with full file contents.
- Semantic Pattern Discovery: Replaces broad glob patterns (like src/**/*.ts) with concept-based searches to find relevant logic, such as authentication flows or API integrations, more accurately than filename matching.
- Automated Guardrails for Agents: Serves as an 'interception protocol' that forces the agent to evaluate the most efficient data retrieval method before executing resource-heavy commands.
| 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:
- Is claudemem indexed? →
claudemem status - Can this be one semantic query? → Often yes
- 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